Video Generation API · Tenant Integration Guide

Version v5 · 2026-10-09 · Somobai Video Generation Platform (changelog in §12)

The public API is compatible with the official Volcano Engine Ark API. If you have already integrated Ark video generation, migrating to this platform takes two changes: the domain and the credential. Request and response fields are unchanged. The asset library also offers a signed entry point compatible with the official Volcano Engine SDK (§9).

1. Quick Start

Three steps to your first video:

# 1. Check that your key works (lists the models you can use)
curl https://api.somobai.com/v1/models \
  -H "Authorization: Bearer sk-your-key-here"

# 2. Create a video task
curl -X POST https://api.somobai.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "doubao-seedance-2-0-260128",
        "content": [{"type": "text", "text": "A cat running across a meadow"}],
        "resolution": "720p",
        "duration": 5
      }'
# → {"id":"cgt-20260827103000-a1b2c"}

# 3. Poll until the task reaches a terminal state
curl https://api.somobai.com/api/v3/contents/generations/tasks/cgt-20260827103000-a1b2c \
  -H "Authorization: Bearer sk-your-key-here"

2. Authentication

All data-plane endpoints use a Bearer token:

Authorization: Bearer sk-xxxxxxxxxxxx

• Keys are issued when your tenant account is opened. You can also create them yourself in the tenant console at /console → API Keys.
• A key created in the console is shown in plain text only once. Store it in your secrets manager right away; if you lose it, contact the platform to have it reissued.
• Each key can be configured with a model allowlist, an IP allowlist, a sub-quota cap and an expiry date.
• If a key leaks, Disable or Rotate it in the console. Rotation invalidates the old key immediately and returns a new one.

IP allowlist (required)

• An account-level IP allowlist is required when your account is opened or registered. Enter the public IPs of the servers that will call the API (comma-separated, CIDR supported, e.g. 203.0.113.7, 198.51.100.0/24). Ranges that open everything, such as 0.0.0.0/0, are rejected.
• Only allowlisted IPs can call the API. This applies to Bearer keys and to the AK/SK entry point in §9; signing in to the web console is not affected.
• If your server IPs change, update them in the console under Settings → API IP allowlist (owner/admin roles). Changes take effect immediately.
• A key's own IP allowlist is optional and narrows the account allowlist further (a request must satisfy both).

Authentication errors

3. Video Generation

3.1 Create a task

POST /api/v3/contents/generations/tasks

Request headers

Request body (same shape as the native Ark fields)

Seedance 2.5 extended fields (passed through unchanged; effective as far as the model supports them)

• Media URLs such as content[].image_url.url may be a public HTTPS URL or a platform asset reference asset://{asset_id} (§8.1).
• Images or videos containing real human faces are blocked by content moderation (InputImageSensitiveContentDetected.PrivacyInformation). See §8.2 (real-person verification) for how to handle this.
• safety_identifier is injected automatically by the platform as a per-tenant isolation identifier. Do not send it; any value you send is ignored.
• Ark text-command compatibility: commands at the end of the prompt such as --resolution 1080p --duration 5 (including the short forms --rs/--dur/--rt) are recognized. When they coexist with top-level fields, the text commands win, and billing uses the values that actually take effect.
• Pass-through rules: the request body is forwarded to the model as is. The platform only does the following: replaces asset:// references with the actual asset URLs, injects safety_identifier, receives the upstream callback itself in place of your callback_url (the platform then pushes to your URL when the task reaches a terminal state, see §5), and writes parsed text commands back into the top-level fields. The extended fields above and any other official fields not listed here are passed through unchanged.

Response 200

{"id": "cgt-20260827103000-a1b2c"}

Task IDs use the same format as Ark: cgt-yyyymmddHHmmss-xxxxx (legacy tasks created before 2026-08-27 use task_ + 24 hex characters and can still be queried by their original ID).

Note: the create endpoint returns only the ID, not the status. Query it with §3.3, or configure a webhook (§5).

Errors

3.2 Idempotency

With an Idempotency-Key header, repeated requests with the same key under the same tenant do not create a new task; the ID of the first task is returned:

curl -X POST .../tasks -H 'Idempotency-Key: order-8837' ...
# → {"id":"cgt-20260827103000-a1b2c"}    first call: created
# → {"id":"cgt-20260827103000-a1b2c"}    retry: same ID, no double charge

Use your own business order number as the key. Keys never expire.

Idempotency matches on the key only and does not compare request bodies. The same key with different parameters still returns the first task.

3.3 Query a task

GET /api/v3/contents/generations/tasks/{id}

In progress

{
  "id": "cgt-20260827103000-a1b2c",
  "model": "doubao-seedance-2-0-260128",
  "status": "running",
  "resolution": "720p",
  "duration": 5,
  "error": null,
  "created_at": 1786886334,
  "updated_at": 1786886391
}

Succeeded

{
  "id": "cgt-20260827103000-a1b2c",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "resolution": "720p",
  "duration": 5,
  "error": null,
  "content": {
    "video_url": "https://….mp4?… (valid for about 24 hours; copy it right away, see §6)",
    "last_frame_url": "https://….png?…"
  },
  "usage": {"completion_tokens": 103819, "total_tokens": 103819},
  "created_at": 1786886334,
  "updated_at": 1786886512
}

Failed

{
  "id": "cgt-20260827103000-a1b2c",
  "status": "failed",
  "error": {"code": "InvalidParameter", "message": "..."},
  "created_at": 1786886334,
  "updated_at": 1786886334
}

• created_at / updated_at are Unix seconds (integers, not strings).
• usage.total_tokens is the billable amount for the task and matches your bill exactly; see §7.2.
• resolution / duration are the actual output values (for duration: -1 tasks, the duration chosen by the model is filled in after success).
• Display fields passed through from the model (seed, framespersecond, generate_audio, service_tier, frames) appear flat at the top level when the upstream returns them.

3.4 State machine

Polling advice: make the first query 5 seconds after creation, then every 3–5 seconds. Webhooks (§5) are the better choice over polling.

3.5 Cancel a task

POST /api/v3/contents/generations/tasks/{id}/cancel

{"id": "cgt-20260827103000-a1b2c", "status": "cancelled"}

Limitation: only tasks that are queued and not yet submitted for execution can be cancelled. Otherwise you get:

{"error": {"code": "InvalidState", "message": "仅本地排队中的任务可取消"}}

(The message reads "only tasks in the local queue can be cancelled".) On cancellation the pre-authorized amount is released in full.

3.6 List tasks

GET /api/v3/contents/generations/tasks?status=succeeded

{"items": [ { /* same structure as a single task in §3.3 */ } ]}

• status is optional and filters by status.
• Always returns the most recent 100 tasks, newest first, with no pagination parameters. Use the console for full history.

3.7 List models

GET /v1/models

{
  "object": "list",
  "data": [
    {"id": "doubao-seedance-2-5-260628", "object": "model"},
    {"id": "doubao-seedance-2-0-260128", "object": "model"},
    {"id": "doubao-seedance-2-0-fast-260128", "object": "model"},
    {"id": "doubao-seedance-2-0-mini-260615", "object": "model"}
  ]
}

Only models you have access to and that the platform has enabled are returned. This endpoint is the authoritative list of available models; §3.8 is for reference.

3.8 Models and supported specs

A resolution the model does not support returns 400. duration: -1 is supported by Seedance 2.5 only. The authoritative model list is GET /v1/models (§3.7).

Seedance 2.5 reference asset limits: videos ≤30, images ≤10, audio ≤10, and ≤50 in total per task.

About 4K: the billable amount is about 4× that of 1080p (4 seconds ≈ 777,600 tokens), but the 4K per-token price is lower, so the actual cost is about 2× that of 1080p. See Billing in the console for unit prices.

4. Concurrency and Rate Limiting

• Each tenant has a concurrency limit (default 10, negotiable). Tasks in queued + running count toward it.
• When the limit is exceeded, your tenant policy applies:
• Queue mode (default): the task enters a local queue and is submitted automatically when a slot frees up. If the queue is full or the wait times out (600 seconds by default), you get 429 or the task becomes expired.
• Reject mode: 429 is returned immediately.

429 response

{"error": {"code": "Throttling", "message": "并发已达上限,请稍后重试"}}

(The message reads "concurrency limit reached, please retry later".) In reject mode the response includes a Retry-After: 5 header.

Client advice: on 429, retry with exponential backoff (5s / 10s / 20s / 40s) and use an Idempotency-Key so retries are never charged twice.

5. Webhook Callbacks

Configure one of the following:

• Tenant level: console Settings → Webhook URL + Secret; applies to all tasks.
• Task level: pass callback_url when creating a task; applies to that task only and takes precedence.

A push is sent when the task reaches a terminal state.

Request

POST <your URL>
Content-Type: application/json
X-Relay-Timestamp: 1786886512
X-Relay-Signature: 3f2a9c...

The request body is identical to the §3.3 query response.

Signature verification

X-Relay-Signature = hex(HMAC-SHA256(secret, timestamp + "." + rawBody))

Python example:

import hmac, hashlib, time

def verify(secret: str, ts: str, raw_body: bytes, sig: str) -> bool:
    if abs(time.time() - int(ts)) > 300:      # reject replays older than 5 minutes
        return False
    mac = hmac.new(secret.encode(),
                   (ts + ".").encode() + raw_body,
                   hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, sig)

Compute it over the raw bytes. Do not deserialize and re-serialize the JSON first.

Retries: non-2xx responses are redelivered, up to 5 deliveries in total (first attempt + 4 retries) with backoff of 20s / 40s / 80s / 160s. If all 5 fail, the delivery is marked failed and can be resent manually from the console Webhook page.

Requirements for your endpoint: return 2xx quickly (15-second timeout) and process asynchronously; be idempotent on id (the same task may be delivered more than once).

Strongly recommended: trigger your video copy job from the success callback. The 24-hour window in §6 starts the moment the task succeeds.

6. Video Files (⚠️ 24-hour validity — copy them promptly)

content.video_url / last_frame_url on a succeeded task are temporary signed URLs from the model provider and expire after about 24 hours.

As soon as you receive succeeded, download the files to your own storage (object storage / CDN). The platform does not keep generated outputs; after 24 hours the task's video can no longer be retrieved (the task record and billing details remain available).

• Download with a plain GET; no Authorization header is needed.
• Pair this with webhooks (§5): start your copy job on the success callback so you don't lose time between polls.
• Follow-up generation that references an output (video extension/editing) is bound by the same 24-hour window; start it promptly.
• Reference assets you upload are not affected: they are hosted by the platform, and their download address (URL) can be reissued at any time through the asset detail endpoint.

If your business needs the platform to keep generated outputs (platform-side copy with 30-day persistent URLs), contact the platform to enable archive mode for your tenant.

7. Billing

7.1 Billing modes

One of two modes, as agreed commercially. You can see your mode and remaining balance under Billing in the console:

Balance (default): the platform allocates a balance (CNY), and each task is charged unit price × billable amount. - Price dimensions: model × scenario × resolution. Requests whose content contains a video_url are priced under the video reference scenario (a lower unit price than pure generation, but more tokens in total). - Your price list is under Billing in the console (unit: CNY per million tokens, the same basis as the official Volcano Engine price list). - The unit price is snapshotted into the task at creation; later price changes do not affect tasks already created. - The billing currency is Chinese yuan (CNY).

Per-model token pool: token quotas are allocated per model (e.g. "1 million tokens for 2.0"). Each task deducts its billable amount in tokens directly from that model's pool. Pools are metered separately and cannot be shared across models, with no currency conversion involved. The console Billing page shows each pool's balance and token ledger, and lets you request more quota per model.

Rules common to both modes: - An estimated amount is frozen at creation; after the terminal state the task is settled at the actual billable amount and the difference is released (tasks with duration: -1 are frozen based on the model's maximum duration). - failed / cancelled / expired tasks are released in full and not charged. - If balance or quota is insufficient, task creation returns 403 QuotaExceeded; you can request an adjustment in the console.

7.2 Billable amount

usage.total_tokens is the billable amount and matches your bill exactly:

The billable amount is the usage actually returned by the model (usage.total_tokens is what you are billed). The table below gives reference estimates per tier (production values deviate slightly) for cost planning and sanity checks:

billable tokens = encoded width × encoded height × (24 × output seconds + 1) ÷ 1024

Estimate formula: width × height × (24 × seconds + 1) ÷ 1024 (the 4K tier has no +1 constant). Seedance 2.5 uses standard pixel dimensions as its encoded size.

Video reference tasks (content contains video_url) are billed by the amount the model actually processes: the input video duration also consumes tokens and a minimum usage applies. The usage.total_tokens returned after success is authoritative.

Asset and real-person verification endpoints do not consume video quota.

8. Asset Library and Real-Person Verification (optional)

Two ways to bring your own content into generation; use whichever fits:

All resources are isolated per tenant (cross-tenant access always returns 404).

8.1 Asset library (platform-hosted)

Assets are hosted by the platform: an upload returns an asset ID that is usable immediately, and at generation time the platform distributes the asset to the executing service line automatically. You never need to know which line holds an asset, and line failures or changes don't affect your assets or references.

POST   /api/seedance/proxy/assets/groups        Create asset group (instant)
GET    /api/seedance/proxy/assets/groups        List asset groups
GET    /api/seedance/proxy/assets/groups/{id}   Asset group detail
PUT    /api/seedance/proxy/assets/groups/{id}   Update
DELETE /api/seedance/proxy/assets/groups/{id}   Delete (group must be empty)

POST   /api/seedance/proxy/assets               Create asset (requires an asset group)
GET    /api/seedance/proxy/assets               List assets (?GroupId=)
GET    /api/seedance/proxy/assets/{id}          Asset detail (includes downloadable URL)
PUT    /api/seedance/proxy/assets/{id}          Update
DELETE /api/seedance/proxy/assets/{id}          Delete

Authentication is the same as §2 (Bearer). Request and response bodies mirror the official Volcano Engine asset API (PascalCase fields wrapped in Result). Resource IDs look like asset-yyyymmddHHmmss-xxxxx / group-yyyymmddHHmmss-xxxxx, and CreateTime is an RFC 3339 timestamp in UTC+8 (e.g. 2026-08-26T18:00:00+08:00).

Key fields

Referencing an asset: put asset://{asset_id} in the url field of the corresponding media object in the video task's content.

• Assets are not pinned to a service line; tasks are scheduled automatically as usual. The first time an asset is used on a given line, the platform distributes it on the spot (that task may wait an extra 10–30 seconds; later tasks using the same asset are unaffected).
• Referencing someone else's asset returns 404; referencing an asset that isn't ready (just uploaded, or rejected by moderation) returns 400.
• Asset size limits (for reference): images ≤30MB; videos ≤200MB / 2–15 seconds; audio ≤15MB / 2–15 seconds.

8.2 Real-person verification (using a specific person's likeness)

Official compliance rules: images or videos containing real human faces cannot be used directly as input (they are blocked with InputImageSensitiveContentDetected.PrivacyInformation). The person must first authorize use through liveness verification:

POST   /api/seedance/face-verifications         Start real-person verification
GET    /api/seedance/face-verifications/{id}    Verification result

Flow:

1. POST /api/seedance/face-verifications (the body may be empty; some lines support return_url) → returns verification_id, h5_url, and expires_in/expires_at (the H5 session lifetime — usually short, so direct the user to open it immediately)
2. Have the consenting person themselves open h5_url in a mobile browser and complete liveness verification as prompted (lighting or angle may cause a failure; retrying is fine)
3. Poll GET /api/seedance/face-verifications/{id}: waiting_user = not finished yet (if the response carries a note saying the session expired, start again from step 1); verified = success, and you get a group_id (the real-person portrait group); failed/expired = start over
4. Upload images/videos/audio of that same person to the group_id (same asset endpoints as §8.1; the upstream checks face consistency — clear frontal photos are recommended, and videos are admitted only if every sampled frame passes). Once the asset is Active, reference it as asset://{asset_id}
5. One portrait group can hold multiple looks of the same person, so one verification is enough; verify and group different people separately

Note: real-person assets are bound to the line on which verification was done (authorization is tied to that line's account), so tasks referencing them always run on that line. This is the only exception to the "assets are not pinned to a line" rule in §8.1.

9. Native Volcano Engine Ark-Compatible Entry Point (optional)

If you already have asset-library code built on the official Volcano Engine SDK, just change the endpoint — your signing logic stays the same:

POST https://api.somobai.com/?Action={Action}&Version=2024-01-01

Create the AK/SK under console Settings. Supported Actions:

CreateAssetGroup ListAssetGroups GetAssetGroup UpdateAssetGroup DeleteAssetGroup CreateAsset ListAssets GetAsset UpdateAsset DeleteAsset

Responses are wrapped in ResponseMetadata / Result, matching the official Volcano Engine format. This entry point operates on the same platform asset library as the §8.1 REST endpoints, and the two can be mixed. Project and credential fields such as ProjectName are handled by the platform automatically — you don't need to, and shouldn't, send them.

Use the Bearer endpoints (§3 / §8.2) for video generation tasks and real-person verification; the signed entry point currently covers the asset library only.

10. Error Reference

All data-plane errors share one format:

{"error": {"code": "ErrorCode", "message": "Error description"}}

Error message texts are currently returned in Chinese; branch on code, not on message.

11. Integration Checklist

• [ ] Keys are stored in a secrets manager — never hard-coded or committed to a repository
• [ ] Every create request carries an Idempotency-Key (your business order number)
• [ ] 429 / 502 / 500 are retried with exponential backoff; 400 / 403 are not retried
• [ ] Webhooks replace high-frequency polling, with signature verification, timestamp checks and idempotency on id
• [ ] Copy video_url immediately in the success callback (24-hour validity; the platform does not keep generated outputs)
• [ ] For use cases involving a specific real person: complete real-person verification (§8.2) first, then upload and reference portrait assets
• [ ] Choose models from GET /v1/models; send a positive integer duration for the 2.0 family, and use -1 with 2.5 only
• [ ] Your state handling covers the 6 public states and treats any unknown state as "in progress"
• [ ] Reconcile with usage.total_tokens (the billable amount) against the console Billing ledger
• [ ] Run the full flow end to end on a small quota before going to production

12. Changelog