Upload a Youzu Asset

Use a Youzu asset when a Merchant API image is not already available at a public HTTP(S) URL. Include the target catalogueId explicitly when requesting upload credentials. The API key identifies the client; it does not select a catalogue. Use the returned asset_id as an image reference in suggestion or moderation requests for that catalogue.

This guide uses Merchant API v2. The upload procedure is identical on v1; its response also contains "sections": {"asset_upload": "complete"}.

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

1. Request upload credentials

Use your reusable customer API key to request an upload URL. Do not create or send a single-use bearer or x-token credential for this Merchant API request:

curl -X POST https://platform.youzu.ai/api/v2/merchant-api/assets/upload-url \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogueId": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "shoe-front.webp",
    "content_type": "image/webp",
    "size_bytes": 483920
  }'

The requested catalogue must belong to the authenticated client, be enabled and ready, and support Merchant API. A catalogue that is missing, deleted, or owned by another client returns 404; a disabled, unready, or unsupported catalogue returns 409.

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

{
  "status": "complete",
  "errors": [],
  "asset_id": "asset_v1_eyJjIjoiYWNtZSIsImciOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJzIjo0ODM5MjAsInQiOiJpbWFnZS93ZWJwIiwidSI6Imh0dHBzOi8vY2RuLmV4YW1wbGUuY29tL3Byb2R1Y3RzL3Nob2UtZnJvbnQud2VicCJ9.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
}

expires_at is the expiration time as a Unix timestamp in milliseconds. 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 storage credentials expire, use the same reusable API key to request a new upload URL.

3. Use the asset ID

Pass the returned asset_id in the images array of a Merchant API suggestion or moderation request:

{
  "catalogueId": "550e8400-e29b-41d4-a716-446655440000",
  "images": ["asset_v1_eyJjIjoiYWNtZSIsImciOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJzIjo0ODM5MjAsInQiOiJpbWFnZS93ZWJwIiwidSI6Imh0dHBzOi8vY2RuLmV4YW1wbGUuY29tL3Byb2R1Y3RzL3Nob2UtZnJvbnQud2VicCJ9.XXG6dW5GHvFKCPldRL15yG2s3wHlSHe7WE5OdCrvJhg"]
}

The signed asset ID belongs to the explicitly selected catalogue that created it and cannot be used from another catalogue. Use that same catalogueId in the suggestion or moderation request. Merchant API does not create or retain an asset record. See Merchant API for image moderation limits and response handling.

Upload products and track status

Check moderation results