Skip to content
Documentation navigation
On this page

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

FieldTypeRules
modelstringRequired. An enabled model such as magi-2.
contentarrayRequired, 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.
durationintegerRequired. Output duration of 4–30 seconds, inclusive.
ratiostringRequired. 21:9, 16:9, 4:3, 1:1, 3:4, 9:16.
resolutionstringExplicitly specify 540p or 1080p.
seedintegerOmit or pass -1 to select a random positive seed. A value from 0 to 4294967295, inclusive, fixes the seed.
generate_audiobooleanDefaults to true. Controls the output audio track.
omni_reference_task_typestringOptional. 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.

typeRequired fieldrole and meaningPer generation
texttext (nonblank string)OmitUp to 1 item
image_urlimage_url.url (string)reference_image for a general reference, first_frame for the start, last_frame for the endUp to 10 general references, or one image per frame role
video_urlvideo_url.url (string)reference_video (required)Up to 3 videos, ≤ 15 s combined
audio_urlaudio_url.url (string)reference_audio (required)Up to 3 audio clips, ≤ 30 s combined
  • General references can be combined. Set reference_image explicitly even for one general reference image. If there is exactly one image and no other media, omitting role or setting it to null makes that image the first_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.

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

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

json
{
  "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"
  }
}
StatusAction
queued / runningContinue polling.
succeededDownload from content.video_url. The link is valid for one hour. Retrieve the task again to refresh it.
failed / expired / cancelledStop polling. On failure or expiry, inspect error.code and error.message.
Result fieldTypeAvailability
created_at, updated_atintegerAlways present. Unix timestamps in seconds.
content.video_urlstringPresent on success. Download directly without an API key.
error.code, error.messagestringOn failure or expiry, these describe the task failure.
duration, framespersecond, seedintegerOn success when known. Delivered duration in whole seconds rounded down, frame rate in frames per second, and seed, respectively.
resolution, ratio, generate_audiostring / string / booleanOn success when known. Delivered resolution, aspect ratio and whether the video has an audio track, respectively.

Python SDK example

python
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.

json
{
  "error": {
    "code": "InvalidParameter",
    "type": "BadRequest",
    "param": "content[1].role",
    "message": "Invalid parameter 'content[1].role': unsupported role for this media input."
  }
}
HTTPCommon codes
400InvalidParameter, MissingParameter, InvalidEndpointOrModel.NotFound, InputSensitiveContentDetected, InsufficientBalance
401 / 403AuthenticationError / AccessDenied
404ResourceNotFound, AssetNotFound
413JSON body exceeds the total size limit.
429RateLimitExceeded
500 / 503InternalServiceError / ServiceUnavailable