Seedance virtual-human asset API

Virtual-human assets are for AI-generated or fictional characters such as brand mascots, digital presenters, or game characters. Create the asset once and reference the same uri in every video to keep the character's look consistent.

The API is asynchronous: the create call returns immediately, Volcengine processes the image in the background, and you poll until the status is Active.

• A LaoZhang API key. The asset API only checks that the key is valid and accepts any group, but generating videos with the asset requires a SeeDance2-group key. Use the same SeeDance2 key for both, because an asset id can only be queried with the key that created it.
• A server of your own. Browsers cannot call the API directly, and the key must stay out of front-end code.
• An HTTPS image URL that anyone on the internet can download without logging in and without hotlink protection.
• Persistent storage for the returned id and uri. YingTu does not keep assets created through the API and has no list endpoint.

1. 1

   Your server

   Host the character image at a public HTTPS URL and call POST /api/seedance-assets/virtual-humans.

2. 2

   YingTu

   Validates the key and body, creates the asset at Volcengine, and returns 202 right away. status is usually Processing at this point.

3. 3

   Your server

   Stores the returned id and uri, then calls GET /api/seedance-assets/virtual-humans/{id} every 5–10 seconds.

4. 4

   Volcengine

   Downloads and processes the image. The status becomes Active (ready) or Failed (the failure object says why).

5. 5

   Your server

   Stops polling at Active and passes the uri as a reference_image to LaoZhang's Seedance video API. Reuse the same uri from then on.

YingTu validates your key by calling LaoZhang's /v1/models with it and caches a successful result for 5 minutes per server instance. A key you just disabled can therefore keep working for up to 5 minutes. If LaoZhang's validation service is unreachable you get 503 authentication_unavailable; retry later.

status is passed through from Volcengine unchanged. Treat any value not listed here as not ready and keep polling; if it does not change for a long time, contact support with the request_id. If YingTu cannot read the status right after creation, the create response also reports Processing.

Every error uses the same shape. Look at both the HTTP status and error.code. error.retryable: true means an identical retry may succeed; false means you need to change the request or contact support. This example is a real response:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
X-Request-Id: req_42480b1cfd2147439b8c514ad8688ab0

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown request field: consent_reference.",
    "request_id": "req_42480b1cfd2147439b8c514ad8688ab0",
    "retryable": false
  }
}

Two responses do not use this JSON shape: a wrong HTTP method (for example GET on a create endpoint) returns 405 with no body, and an expired real-person callback relay shows the person's browser a 400 (see Verification callback).

• Each API key gets at most 12 write requests per hour, counted across all POST endpoints together: creating virtual-human assets, creating real-person verification sessions, and creating real-person assets. GET requests are not counted.
• Every POST that passes key validation counts, including requests rejected with 400, 403, 409, 410, 413, or 415 and requests that fail upstream. 401 responses do not count. Validate parameters on your side before sending.
• The window starts with the first POST in the hour and resets completely one hour later. It is not a sliding window.
• Successful POST responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (window reset time in Unix seconds). Error responses do not include these headers.
• Over the limit you get 429 rate_limit_exceeded with Retry-After in seconds. Throttling by Volcengine also returns 429, but without Retry-After.
• If this quota is too low for your volume, contact YingTu support.

X-Request-Id: req_4f0c2a9e8b7d4c1fa3e56b7d9c0e1f2a
X-RateLimit-Limit: 12
X-RateLimit-Remaining: 11
X-RateLimit-Reset: 1790326800

Videos are not generated by the YingTu asset API. Call LaoZhang's Seedance endpoint POST https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks instead, with a key from the SeeDance2 group.

• Add an image_url item to the content array: set url to the asset's uri (asset://...) and role to reference_image.
• Only use assets whose status is Active. Do not submit assets that are still Processing or have Failed.
• Reuse the same uri in as many tasks as you like; there is no need to create the asset again.
• Reference images per task are capped: up to 9 for the Seedance 2.0 models and up to 30 for Seedance 2.5.
• For every other parameter (model, ratio, duration, resolution, polling the task), follow the LaoZhang Seedance docs.

curl -X POST https://api.laozhang.ai/seedance/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      { "type": "text", "text": "The character from the reference image walks slowly toward the camera on a rainy neon street at night, cinematic lighting" },
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-20260925080012-x7k2p" },
        "role": "reference_image"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "watermark": false,
    "generate_audio": false
  }'

A successful call returns { "id": "cgt-..." }; poll GET .../contents/generations/tasks/{id} for the result.

Create an asset and wait until it is ready. Set the LAOZHANG_API_KEY environment variable first.

import os
import time

import requests

BASE_URL = "https://yingtu.ai/api/seedance-assets"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def api(method, path, **kwargs):
    resp = requests.request(method, BASE_URL + path, headers=HEADERS, timeout=60, **kwargs)
    body = resp.json()
    if not resp.ok:
        err = body["error"]
        raise RuntimeError(f"{resp.status_code} {err['code']}: {err['message']} ({err['request_id']})")
    return body


asset = api("POST", "/virtual-humans", json={
    "image_url": "https://cdn.example.com/characters/luna.png",
    "name": "luna-v1",
})
# Store id and uri in your database before polling
for _ in range(120):  # poll for up to ~10 minutes
    if asset["status"] in ("Active", "Failed"):
        break
    time.sleep(5)
    asset = api("GET", f"/virtual-humans/{asset['id']}")

if asset["status"] == "Active":
    print("Ready for generation:", asset["uri"])
else:
    print("Processing failed:", asset["status"], asset.get("failure"))

// Node.js 18+. Save as virtual-human.mjs and run: node virtual-human.mjs
const BASE_URL = "https://yingtu.ai/api/seedance-assets";
const AUTH = { Authorization: "Bearer " + process.env.LAOZHANG_API_KEY };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function api(path, init = {}) {
  const res = await fetch(BASE_URL + path, {
    ...init,
    headers: { ...AUTH, ...init.headers },
    signal: AbortSignal.timeout(60_000),
  });
  const body = await res.json();
  if (!res.ok) {
    const { code, message, request_id } = body.error;
    throw new Error(res.status + " " + code + ": " + message + " (" + request_id + ")");
  }
  return body;
}

let asset = await api("/virtual-humans", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    image_url: "https://cdn.example.com/characters/luna.png",
    name: "luna-v1",
  }),
});
// Store asset.id and asset.uri in your database before polling
for (let i = 0; i < 120 && !["Active", "Failed"].includes(asset.status); i++) {
  await sleep(5000);
  asset = await api("/virtual-humans/" + asset.id);
}
console.log(asset.status, asset.status === "Active" ? asset.uri : asset.failure);

• 2026-09-25: Rewrote the documentation after checking every statement against the live API code. Added the end-to-end flow, callback details, the full error table and the FAQ. API behavior did not change.