Upload a Youzu Asset

Use a Youzu asset when a Merchant API image is not already available at a public HTTPS URL. The upload is catalogue-scoped and returns an opaque asset_id that Merchant API suggestion endpoints can use as an image reference.

JPEG, PNG, and WebP images are supported up to 15 MiB each.

1. Request upload credentials

Create a single-use merchant-api token with the asset-upload action as described in Authentication, then request an upload URL:

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/assets/upload-url \
  -H "Authorization: Bearer YOUR_ASSET_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "shoe-front.webp",
    "content_type": "image/webp",
    "size_bytes": 483920
  }'

The response contains the asset ID and short-lived storage credentials:

{
  "status": "complete",
  "sections": {"asset_upload": "complete"},
  "errors": [],
  "asset_id": "asset_v1_eyJjIjoiYWNtZSIsImciOiJob21lIiwicyI6NDgzOTIwLCJ0IjoiaW1hZ2Uvd2VicCIsInUiOiJodHRwczovL2Nkbi5leGFtcGxlLmNvbS9wcm9kdWN0cy9zaG9lLWZyb250LndlYnAifQ.XXG6dW5GHvFKCPldRL15yG2s3wHlSHe7WE5OdCrvJhg",
  "upload_url": "https://storage.example/upload/...",
  "authorization_token": "SHORT_LIVED_UPLOAD_TOKEN",
  "upload_key": "4cfe61ba-7319-45e8-b272-2a5c291bb7a0.webp",
  "cdn_url": "https://cdn.example/file/youzu/4cfe61ba-7319-45e8-b272-2a5c291bb7a0.webp",
  "expires_at": 1784894700000
}

Treat upload_url and authorization_token as credentials. Keep them on your server and do not log or persist them.

2. Upload the image bytes

Before expires_at, send the exact file to upload_url using the returned storage values:

curl -X POST "UPLOAD_URL" \
  -H "Authorization: SHORT_LIVED_UPLOAD_TOKEN" \
  -H "X-Bz-File-Name: UPLOAD_KEY" \
  -H "Content-Type: image/webp" \
  -H "X-Bz-Content-Sha1: do_not_verify" \
  --data-binary @shoe-front.webp

The uploaded bytes must match the content_type and size_bytes supplied when the upload URL was requested. If the credentials expire, create a new asset-upload token and request a new upload URL.

3. Use the asset ID

Pass the opaque asset_id, not the upload credentials, in the images array of a Merchant API suggestion request:

{
  "images": ["asset_v1_eyJjIjoiYWNtZSIsImciOiJob21lIiwicyI6NDgzOTIwLCJ0IjoiaW1hZ2Uvd2VicCIsInUiOiJodHRwczovL2Nkbi5leGFtcGxlLmNvbS9wcm9kdWN0cy9zaG9lLWZyb250LndlYnAifQ.XXG6dW5GHvFKCPldRL15yG2s3wHlSHe7WE5OdCrvJhg"]
}

The signed asset ID belongs to the catalogue that created it and cannot be used from another catalogue. Merchant API does not create or retain an asset record. See Merchant API for image review limits and response handling.