Upload an asset
POST /v1/assets · multipart/form-data
Upload a single file using an organization API key, then reference it in a native v2 or Ark generation.
Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | One file with a supported filename extension. |
Use cURL -F or the client’s FormData to generate the multipart boundary. The complete multipart request is limited to 201,048,576 bytes.
Example request
curl "https://api.sand.ai/v1/assets" \
-H "Authorization: Bearer $SAND_API_KEY" \
-F "file=@./reference.png"
Response
200 OK
{ "id": 123456789 }
The response id is a JSON number (int64). In JavaScript, use a lossless JSON parser before converting the ID to a decimal string.
| Interface | Image reference |
|---|---|
v2 · assetId | {"type":"reference_image","image":{"assetId":"123456789"}} |
v2 · url | {"type":"reference_image","image":{"url":"asset://123456789"}} |
| Ark | {"type":"image_url","role":"reference_image","image_url":{"url":"asset://123456789"}} |
Media limits
| Type | Formats | Per file | Per task |
|---|---|---|---|
| Image | JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF | Under 30,000,000 bytes | Up to 10 |
| Video | MP4 / MOV (H.264 / H.265) | ≤ 200,000,000 bytes, 2–15 s | Up to 3, ≤ 15 s total |
| Audio | WAV / MP3 | ≤ 15,000,000 bytes, 2–30 s | Up to 3, ≤ 30 s total |
Duration bounds are inclusive. Count each occurrence of a repeated reference. The audio total counts standalone audio files only. Decoding and content checks may still fail after generation is accepted.
Uploaded images must be 16–10,000 pixels per side, at most 16,000,000 pixels in total, with the longer side at most 100 times the shorter side. Reference videos may omit audio. MP4 supports embedded AAC or MP3. MOV also supports PCM.
Upload errors
The following errors return HTTP 400. Preserve the leading zeros in the string code.
| Code | Cause |
|---|---|
00003 | Missing multipart boundary or file, wrong file field, no filename extension, or multiple files. |
00200 | Unsupported file extension. |
00202 | Invalid file content, image dimensions or media duration. |
00204 | File or complete request exceeds its byte limit. |