Skip to content
Documentation navigation
On this page

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

FieldTypeRequiredDescription
filebinaryYesOne 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

bash
curl "https://api.sand.ai/v1/assets" \
  -H "Authorization: Bearer $SAND_API_KEY" \
  -F "file=@./reference.png"

Response

200 OK

json
{ "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.

InterfaceImage 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

TypeFormatsPer filePer task
ImageJPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIFUnder 30,000,000 bytesUp to 10
VideoMP4 / MOV (H.264 / H.265)≤ 200,000,000 bytes, 2–15 sUp to 3, ≤ 15 s total
AudioWAV / MP3≤ 15,000,000 bytes, 2–30 sUp 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.

CodeCause
00003Missing multipart boundary or file, wrong file field, no filename extension, or multiple files.
00200Unsupported file extension.
00202Invalid file content, image dimensions or media duration.
00204File or complete request exceeds its byte limit.