Create a generation
POST /v2/generations · Content-Type: application/json
| Field | Type | Rules |
|---|---|---|
model | string | Required. An enabled model, such as magi-2. |
parts | array | Required, 1–17 items. Include exactly one nonblank text item of up to 15,000 Unicode code points, plus any media references in input order. |
duration | integer | Required. Output duration in whole positive seconds. |
aspectRatio | string | Required. Use width:height with 1–5 digits per side and no leading zeros, e.g. 16:9. |
resolution | string | Allowed 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. |
generateAudio | boolean | Defaults to true. Audio references are accepted even when set to false. |
seed | integer | Omit 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.
type | Required field | Example item | Per generation |
|---|---|---|---|
text | text (string) | {"type":"text","text":"Move the camera slowly forward."} | Exactly one, at any position |
reference_image | image (object) | {"type":"reference_image","image":{"assetId":"101"}} | Up to 10 images |
reference_video | video (object) | {"type":"reference_video","video":{"assetId":"102"}} | Up to 3 videos, ≤ 15 s combined |
reference_audio | audio (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.
| Source | Type | Value |
|---|---|---|
assetId | string | Upload 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) | string | A 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) | string | Use 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.
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
{
"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.