Ark compatibility
Create and retrieve video tasks with the Ark SDK or HTTP, using references or first and last frames.
Create video generation tasks and retrieve them by ID using the Ark Python SDK or HTTP. Authenticate with your organization’s Sand API key.
SDK base_url https://api.sand.ai/compatible/ark/api/v3
Authorization: Bearer <API_KEY>
Create a task
POST /compatible/ark/api/v3/contents/generations/tasks · Content-Type: application/json
| Field | Type | Rules |
|---|---|---|
model | string | Required. An enabled model such as magi-2. |
content | array | Required, 1–17 items. Text-only input needs one nonblank text item. With any media, including audio alone, text is optional. At most one text item of up to 15,000 Unicode code points. |
duration | integer | Required. Output duration of 4–30 seconds, inclusive. |
ratio | string | Required. 21:9, 16:9, 4:3, 1:1, 3:4, 9:16. |
resolution | string | Explicitly specify 540p or 1080p. |
seed | integer | Omit or pass -1 to select a random positive seed. A value from 0 to 4294967295, inclusive, fixes the seed. |
generate_audio | boolean | Defaults to true. Controls the output audio track. |
omni_reference_task_type | string | Optional. Only auto is supported. |
The selected model must support the requested combination of input type, resolution, aspect ratio and duration. Omit watermark. Any boolean value, including false, returns HTTP 400.
Prompt suffixes Use top-level JSON fields for generation options. Alternatively, a text item in content[] may end with options. For example, Ocean waves --rt 16:9 --dur 5 --rs 1080p sets the prompt to “Ocean waves”, the aspect ratio to 16:9, the duration to 5 seconds and the resolution to 1080p. An explicit top-level field takes precedence. With "duration": 8, the duration is 8 seconds.
Unsupported create parameters Omit frames, output_format, camera_fixed, return_last_frame, draft, service_tier, callback_url, execution_expires_after, priority, safety_identifier and tools. For these fields, null is treated as omitted. Any other value, including false or 0, returns HTTP 400 with error code InvalidParameter.
content[] types and roles
role is a string on the item, alongside type. Each item contains one kind of content. For a media item, the name of the object containing url must match type.
type | Required field | role and meaning | Per generation |
|---|---|---|---|
text | text (nonblank string) | Omit | Up to 1 item |
image_url | image_url.url (string) | reference_image for a general reference, first_frame for the start, last_frame for the end | Up to 10 general references, or one image per frame role |
video_url | video_url.url (string) | reference_video (required) | Up to 3 videos, ≤ 15 s combined |
audio_url | audio_url.url (string) | reference_audio (required) | Up to 3 audio clips, ≤ 30 s combined |
- General references can be combined. Set
reference_imageexplicitly even for one general reference image. If there is exactly one image and no other media, omittingroleor setting it tonullmakes that image thefirst_frame. - Frame inputs accept a first frame alone or a first and last frame together. The roles identify the frames in either array order. A prompt is optional. General image, video and audio references cannot be added to a frame request.
Media URLs Use asset://<ID> with the positive decimal int64 ID returned by POST /v1/assets for the same organization, with no leading zeros. All three media types accept public HTTPS download URLs that require no authentication. Images and audio also accept data:<MIME>;base64,<data>. Image MIME types are image/jpeg, image/jpg, image/png, image/webp, image/gif, image/bmp, image/tiff, image/heic and image/heif. Audio MIME types are audio/mpeg, audio/mp3, audio/wav and audio/x-wav. The JSON request is limited to 64,000,000 bytes, including at most 2 MiB of non-media JSON. See Upload an asset for per-file limits.
A general image reference takes the form {"type":"image_url","role":"reference_image","image_url":{"url":"asset://101"}}.
First and last frame example
Upload the two images, replace 101 and 102 with their respective asset IDs, and send this JSON as the create request body.
{
"model": "magi-2",
"content": [
{
"type": "text",
"text": "Transition smoothly from the coast at dawn to the coast at sunset."
},
{
"type": "image_url",
"role": "first_frame",
"image_url": {
"url": "asset://101"
}
},
{
"type": "image_url",
"role": "last_frame",
"image_url": {
"url": "asset://102"
}
}
],
"duration": 5,
"ratio": "16:9",
"resolution": "1080p"
}
Create response HTTP 200. Save the string id. Creation is not idempotent. Do not automatically resubmit after a lost response.
{
"id": "987654321"
}
Retrieve a task
GET /compatible/ark/api/v3/contents/generations/tasks/{id}
The path parameter id is the task ID returned at creation. No request body. Successful retrieval returns HTTP 200.
{
"id": "987654321",
"model": "magi-2",
"status": "succeeded",
"created_at": 1794614400,
"updated_at": 1794614460,
"service_tier": "default",
"draft": false,
"content": {
"video_url": "https://files.example.com/video.mp4?signature=example"
}
}
| Status | Action |
|---|---|
queued / running | Continue polling. |
succeeded | Download from content.video_url. The link is valid for one hour. Retrieve the task again to refresh it. |
failed / expired / cancelled | Stop polling. On failure or expiry, inspect error.code and error.message. |
| Result field | Type | Availability |
|---|---|---|
created_at, updated_at | integer | Always present. Unix timestamps in seconds. |
content.video_url | string | Present on success. Download directly without an API key. |
error.code, error.message | string | On failure or expiry, these describe the task failure. |
duration, framespersecond, seed | integer | On success when known. Delivered duration in whole seconds rounded down, frame rate in frames per second, and seed, respectively. |
resolution, ratio, generate_audio | string / string / boolean | On success when known. Delivered resolution, aspect ratio and whether the video has an audio track, respectively. |
Python SDK example
import os
import time
from volcenginesdkarkruntime import Ark
client = Ark(
base_url="https://api.sand.ai/compatible/ark/api/v3",
api_key=os.environ["SAND_API_KEY"],
max_retries=0,
)
job = client.content_generation.tasks.create(
model="magi-2",
content=[{"type": "text", "text": "A slow camera push toward waves breaking against the rocks."}],
duration=5,
ratio="16:9",
resolution="540p",
)
print(job.id)
while True:
time.sleep(10)
task = client.content_generation.tasks.get(task_id=job.id)
if task.status == "succeeded":
print(task.content.video_url)
break
if task.status in ("failed", "cancelled", "expired"):
print(task.status, task.error)
break
Errors
Non-2xx responses contain error.code, error.type and error.message. A field error may include error.param. Keep the X-Request-Id response header for troubleshooting.
For an HTTP 400 field error, error.param identifies the request field.
{
"error": {
"code": "InvalidParameter",
"type": "BadRequest",
"param": "content[1].role",
"message": "Invalid parameter 'content[1].role': unsupported role for this media input."
}
}
| HTTP | Common codes |
|---|---|
| 400 | InvalidParameter, MissingParameter, InvalidEndpointOrModel.NotFound, InputSensitiveContentDetected, InsufficientBalance |
| 401 / 403 | AuthenticationError / AccessDenied |
| 404 | ResourceNotFound, AssetNotFound |
| 413 | JSON body exceeds the total size limit. |
| 429 | RateLimitExceeded |
| 500 / 503 | InternalServiceError / ServiceUnavailable |