Skip to content
Documentation navigation
On this page

Create a generation

POST /v2/generations · Content-Type: application/json

FieldTypeRules
modelstringRequired. An enabled model, such as magi-2.
partsarrayRequired, 1–17 items. Include exactly one nonblank text item of up to 15,000 Unicode code points, plus any media references in input order.
durationintegerRequired. Output duration in whole positive seconds.
aspectRatiostringRequired. Use width:height with 1–5 digits per side and no leading zeros, e.g. 16:9.
resolutionstringAllowed values are 540p and 1080p. Defaults to 1080p when omitted, null, empty or whitespace-only. The model must support the combination of ratio, resolution, duration and input mode.
generateAudiobooleanDefaults to true. Audio references are accepted even when set to false.
seedintegerOmit or pass -1 to select a random positive seed. A value from 0 to 4294967295, inclusive, fixes the seed.

Omit unset optional fields. Only resolution accepts explicit null. Use native JSON numbers and booleans and supply each documented key at most once. Omit watermark on this endpoint, including false.

parts[] structure

Each item is an object. Its type selects the required sibling field. The native API does not accept role. To specify a first or last frame, see Volcengine Ark compatibility.

typeRequired fieldExample itemPer generation
texttext (string){"type":"text","text":"Move the camera slowly forward."}Exactly one, at any position
reference_imageimage (object){"type":"reference_image","image":{"assetId":"101"}}Up to 10 images
reference_videovideo (object){"type":"reference_video","video":{"assetId":"102"}}Up to 3 videos, ≤ 15 s combined
reference_audioaudio (object){"type":"reference_audio","audio":{"url":"https://media.example.com/sound.mp3"}}Up to 3 audio clips, ≤ 30 s combined

Set exactly one of assetId or url in each image, video or audio object. Media references retain their array order. See Upload an asset for supported formats and file sizes.

SourceTypeValue
assetIdstringUpload the matching media type with POST /v1/assets using a key from the same organization. Convert the returned numeric id to its exact decimal string. Use a positive int64 with no leading zeros.
url (HTTPS)stringA public HTTPS download URL of up to 8,192 characters. Signed query parameters are allowed. The download must work without cookies or extra headers. Omit user credentials and URL fragments.
url (uploaded asset)stringUse asset://<id> for an image, video or audio file uploaded by the same organization. The ID follows the same rules as assetId. For example, {"type":"reference_image","image":{"url":"asset://101"}}.

Example request

Replace 123456789 with the image ID returned by POST /v1/assets, preserving its full decimal precision.

bash
curl "https://api.sand.ai/v2/generations" \
  -H "Authorization: Bearer $SAND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
  "model": "magi-2",
  "parts": [
    {
      "type": "text",
      "text": "A slow camera push toward waves breaking against the rocks."
    },
    {
      "type": "reference_image",
      "image": {
        "assetId": "123456789"
      }
    }
  ],
  "duration": 5,
  "aspectRatio": "16:9",
  "resolution": "540p"
}'

Response

202 Accepted · Location: /v2/generations/987654321

json
{
  "id": "987654321"
}

Save the string id for polling. Creation is not idempotent. Resubmitting after a timeout or lost response may create a second billable task. If an error contains details.generation_id, retrieve that ID first.

Invalid parameters return HTTP 400 with invalid_parameter. Keys in details identify the failing field, such as parts[1].role or parts[1].image.assetId.