Seedance real-person asset API

When a video has to show a real person (a host, spokesperson, or instructor), Seedance requires that person's own authorization; an ordinary photo is not enough. This API wraps the authorization into three steps: create a verification session, let the person verify, then create the asset.

The verification page is run by Volcengine (ByteDance's cloud platform) on ark.volcengine.com, and the person needs a device with a camera for the liveness check. YingTu never sees the person's ID documents or face data; it only relays the result.

• 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 throughout, because verification_id and asset id values can only be queried with the key that created them.
• A server of your own. Browsers cannot call the API directly, and the key must stay out of front-end code.
• A callback page (callback_url) at a public HTTPS URL. The person's browser lands there after verification. It is a web page for the person, not a webhook for your server.
• A way to hand the verification link to the person, for example opening it in your app or website, or sending it by SMS or email.
• A public HTTPS URL of a clear, front-facing photo of the person, plus persistent storage for verification_id, id, and uri.

1. 1

   Your server

   Calls POST /api/seedance-assets/real-persons/verifications with a callback_url, stores the returned verification_id next to your user, and hands the verification_url to the person.

2. 2

   The person

   Opens verification_url within 30 minutes, gives consent, and completes the liveness check on Volcengine's official page.

3. 3

   Volcengine → YingTu → the person's browser

   When the flow ends, the person's browser goes to YingTu's relay URL and is redirected (302) to your callback_url with verification_id and result_code appended.

4. 4

   Your server

   When the callback page is opened (or on a timer), calls GET /api/seedance-assets/real-persons/verifications/{verification_id} until status is verified.

5. 5

   Your server

   Before expires_at, calls POST /api/seedance-assets/real-persons with a clear, front-facing photo of the person and receives the asset id and uri (status Processing).

6. 6

   Your server

   Polls GET /api/seedance-assets/real-persons/{id} until Active, then passes the uri as a reference_image to video generation.

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.

Verification session

Asset

Asset status is passed through from Volcengine unchanged. Treat any value not listed here as not ready and keep polling.

When the session is created, YingTu gives Volcengine its own relay URL, not your callback_url. When the person finishes, Volcengine sends their browser to the relay URL, and YingTu redirects the browser (302) to your callback_url:

# 1) Volcengine sends the person's browser to YingTu's relay URL
GET https://yingtu.ai/api/seedance-assets/real-persons/callback/cb_...?bytedToken=...&resultCode=10000

# 2) YingTu answers with a redirect to your callback_url
HTTP/1.1 302 Found
Location: https://app.example.com/seedance/verified?user=42&verification_id=ver_Zp7cM1xRa4...Ty9vB&result_code=10000

• Treat the callback as a signal that the person is back. Anyone can forge the query string, so never decide pass or fail from result_code; always confirm verified with the GET endpoint.
• Check status with the verification_id you stored when creating the session, and use your own callback_url parameters (such as user=42) to find the matching record.
• Volcengine's session token (bytedToken) never appears in the redirected URL.
• The relay URL stops working 35 minutes after the session was created. After that the person sees HTTP 400 with {"error":"Invalid or expired verification callback."} and is not redirected to your page.
• The callback page is for the person. Show something like "Verification submitted, confirming…" and let your server check the result.

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.
• Each real-person asset needs at least two POSTs (verification session + asset), so one key can create about 6 real-person assets per hour. Poll the GET endpoint while waiting for verification instead of retrying POSTs.
• 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.

The whole flow from verification session to a ready asset. Set the LAOZHANG_API_KEY environment variable first. In production, step 2 is usually triggered by your callback page; the samples poll instead.

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


# 1. Create a verification session. Your own query parameters on
#    callback_url are kept when the person is redirected back.
session = api("POST", "/real-persons/verifications", json={
    "callback_url": "https://app.example.com/seedance/verified?user=42",
    "language": "en",
})
verification_id = session["verification_id"]  # store it in your database next to user 42
print("Send this link to the person:", session["verification_url"])

# 2. Wait for the person to pass. Trigger this when your callback page
#    is opened, or just poll. After expires_at this raises 410 verification_expired.
while api("GET", f"/real-persons/verifications/{verification_id}")["status"] != "verified":
    time.sleep(5)

# 3. Create the asset from a clear, front-facing photo of the same person
asset = api("POST", "/real-persons", json={
    "verification_id": verification_id,
    "image_url": "https://cdn.example.com/people/presenter-a.jpg",
    "name": "presenter-a",
})

# 4. Wait until the asset is ready
for _ in range(120):
    if asset["status"] in ("Active", "Failed"):
        break
    time.sleep(5)
    asset = api("GET", f"/real-persons/{asset['id']}")
print(asset["status"], asset["uri"], asset.get("failure"))

// Node.js 18+. Save as real-person.mjs and run: node real-person.mjs
const BASE_URL = "https://yingtu.ai/api/seedance-assets";
const AUTH = { Authorization: "Bearer " + process.env.LAOZHANG_API_KEY };
const JSON_HEADERS = { "Content-Type": "application/json" };
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;
}

// 1. Create a verification session; your own callback_url parameters come back unchanged
const session = await api("/real-persons/verifications", {
  method: "POST",
  headers: JSON_HEADERS,
  body: JSON.stringify({
    callback_url: "https://app.example.com/seedance/verified?user=42",
    language: "en",
  }),
});
const verificationId = session.verification_id; // store it in your database next to user 42
console.log("Send this link to the person:", session.verification_url);

// 2. Wait for the person to pass; after expires_at this throws 410 verification_expired
while ((await api("/real-persons/verifications/" + verificationId)).status !== "verified") {
  await sleep(5000);
}

// 3. Create the asset from a clear, front-facing photo of the same person
let asset = await api("/real-persons", {
  method: "POST",
  headers: JSON_HEADERS,
  body: JSON.stringify({
    verification_id: verificationId,
    image_url: "https://cdn.example.com/people/presenter-a.jpg",
    name: "presenter-a",
  }),
});

// 4. Wait until the asset is ready
for (let i = 0; i < 120 && !["Active", "Failed"].includes(asset.status); i++) {
  await sleep(5000);
  asset = await api("/real-persons/" + asset.id);
}
console.log(asset.status, 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.