REST API 参考

真人素材 API

调用者无需登录 YingTu，但真人本人仍必须在字节官方 H5 页面完成身份验证、授权确认和活体检测。

虚拟人素材 API从一个公网 HTTPS 图片地址创建可复用的虚拟人 Asset ID。真人素材 API创建官方 H5 真人认证会话，查询认证结果并创建已授权的真人 Asset ID。

端点

Base URL

https://yingtu.ai

POST /api/seedance-assets/real-persons/verifications

GET /api/seedance-assets/real-persons/verifications/{verification_id}

POST /api/seedance-assets/real-persons

GET /api/seedance-assets/real-persons/{id}

认证

调用者无需登录 YingTu 或 Google。接口使用 LaoZhang API Key，并仅接受 Authorization: Bearer <LAOZHANG_API_KEY>。

请求头	必填	说明
`Authorization`	是	LaoZhang API Key，使用 Bearer 认证。
`Content-Type`	仅 POST	创建类 POST 请求固定使用 application/json。

请求

POST /api/seedance-assets/real-persons/verifications

字段	必填	说明
`callback_url`	是	认证完成后的 HTTPS 回调地址。
`language`	否	官方 H5 语言：zh、en 或 zh-Hant；默认 zh。

GET /api/seedance-assets/real-persons/verifications/{verification_id}

字段	必填	说明
`verification_id`	是	认证创建响应返回的路径参数。

POST /api/seedance-assets/real-persons

字段	必填	说明
`verification_id`	是	状态必须为 verified，且属于同一 API Key。
`image_url`	是	同一人物清晰正面图片的公网 HTTPS 地址。
`name`	否	素材名称，最多 64 个字符。

创建请求

1. POST /verifications

curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/real-persons/verifications \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "callback_url": "https://customer.example.com/seedance/verified",
    "language": "en"
  }'

2. GET /verifications/{verification_id}

curl --request GET \
  --url https://yingtu.ai/api/seedance-assets/real-persons/verifications/ver_eyJvcGFxdWUiOiJleGFtcGxlIn0 \
  --header "Authorization: Bearer $LAOZHANG_API_KEY"

3. POST /real-persons

curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/real-persons \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "verification_id": "ver_eyJvcGFxdWUiOiJleGFtcGxlIn0",
    "image_url": "https://cdn.example.com/presenter.webp",
    "name": "presenter-a"
  }'

响应示例

POST /verifications · 201

HTTP/1.1 201 Created
Content-Type: application/json

{
	  "request_id": "req_01JZEXAMPLE",
	  "verification_id": "ver_eyJvcGFxdWUiOiJleGFtcGxlIn0",
	  "status": "requires_user_action",
	  "verification_url": "https://official-h5.example/?...&lng=en",
	  "callback_url": "https://customer.example.com/seedance/verified",
	  "expires_at": "2026-07-29T05:30:00.000Z"
	}

GET /verifications/{id} · 200 pending

{
  "request_id": "req_01JZEXAMPLE",
  "verification_id": "ver_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "status": "pending",
  "expires_at": "2026-07-29T05:30:00.000Z"
}

GET /verifications/{id} · 200 verified

{
  "request_id": "req_01JZEXAMPLE",
  "verification_id": "ver_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "status": "verified",
  "expires_at": "2026-07-29T05:30:00.000Z"
}

POST /real-persons · 409 pending

{
  "error": {
    "code": "verification_pending",
    "message": "The represented person has not completed verification.",
    "request_id": "req_01JZEXAMPLE",
    "retryable": true
  }
}

GET or POST · 410 expired

{
  "error": {
    "code": "verification_expired",
    "message": "The verification session expired. Create a new session.",
    "request_id": "req_01JZEXAMPLE",
    "retryable": false
  }
}

POST /real-persons · 202

{
  "request_id": "req_01JZEXAMPLE",
  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "real_person",
  "name": "presenter-a",
  "status": "Processing",
  "uri": "asset://asset-20260729-example"
}

认证回调

GET https://customer.example.com/seedance/verified
	  ?verification_id=ver_eyJvcGFxdWUiOiJleGFtcGxlIn0
  &result_code=10000

result_code=10000 表示官方 H5 流程已完成。后续 GET 与 POST 请使用回调 Location 中的 verification_id：GET 在 pending 时仍返回 HTTP 200，pending 状态下提前创建素材才返回 HTTP 409；过期 ID 返回 HTTP 410。回调不会暴露字节上游 BytedToken。

字节官方认证页语言

官方文档目前只列出 lng=zh、lng=en、lng=zh-Hant，默认值是 zh。本接口会根据 language 参数设置返回链接。

建议映射：zh→zh，en→en，ru/ja/ko/es→en。繁体中文可使用 zh-Hant；官方目前未公布俄语、日语、韩语或西班牙语认证页。

zh → lng=zh
en → lng=en
ru / ja / ko / es → lng=en
Traditional Chinese → lng=zh-Hant

代码示例

JavaScript · Node.js

const headers = {
  Authorization: `Bearer ${process.env.LAOZHANG_API_KEY}`,
  "Content-Type": "application/json",
};

const begin = await fetch("https://yingtu.ai/api/seedance-assets/real-persons/verifications", {
  method: "POST",
  headers,
  body: JSON.stringify({
    callback_url: "https://customer.example.com/seedance/verified",
    language: "en",
  }),
});

if (!begin.ok) throw new Error(await begin.text());
const session = await begin.json();
const verificationUrl = session.verification_url;
// Deliver verificationUrl only to the represented person's authenticated UI.
// Do not log or persist this short-lived URL.

// After the represented person finishes the official H5 flow:
const callbackVerificationId =
  "<verification_id received at your callback URL>";
const verified = await fetch(
  `https://yingtu.ai/api/seedance-assets/real-persons/verifications/${callbackVerificationId}`,
  { headers: { Authorization: headers.Authorization } },
).then((response) => response.json());

if (verified.status === "verified") {
  const asset = await fetch("https://yingtu.ai/api/seedance-assets/real-persons", {
    method: "POST",
    headers,
    body: JSON.stringify({
      verification_id: callbackVerificationId,
      image_url: "https://cdn.example.com/presenter.webp",
      name: "presenter-a",
    }),
  }).then((response) => response.json());
  console.log(asset);
}

Python · requests

import os
import requests

endpoint = "https://yingtu.ai/api/seedance-assets/real-persons"
verification_endpoint = f"{endpoint}/verifications"
headers = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}

session = requests.post(
    verification_endpoint,
    headers=headers,
    json={
        "callback_url": "https://customer.example.com/seedance/verified",
        "language": "en",
    },
    timeout=30,
)
session.raise_for_status()
verification = session.json()
verification_url = verification["verification_url"]
# Deliver verification_url only to the represented person's authenticated UI.
# Do not log or persist this short-lived URL.

# Run this after the represented person completes the official H5 flow.
callback_verification_id = "<verification_id received at your callback URL>"
status = requests.get(
    f"{verification_endpoint}/{callback_verification_id}",
    headers=headers,
    timeout=30,
)
status.raise_for_status()

if status.json()["status"] == "verified":
    asset = requests.post(
        endpoint,
        headers=headers,
        json={
            "verification_id": callback_verification_id,
            "image_url": "https://cdn.example.com/presenter.webp",
            "name": "presenter-a",
        },
        timeout=60,
    )
    asset.raise_for_status()
    print(asset.json())

查询素材状态

curl --request GET \
	  --url https://yingtu.ai/api/seedance-assets/real-persons/ast_eyJvcGFxdWUiOiJleGFtcGxlIn0 \
	  --header "Authorization: Bearer $LAOZHANG_API_KEY"

状态响应

HTTP/1.1 200 OK
Content-Type: application/json

{
	  "request_id": "req_01JZEXAMPLE",
	  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "real_person",
  "status": "Active",
  "uri": "asset://asset-20260729-example",
	  "created_at": "2026-07-29T05:00:00Z",
	  "updated_at": "2026-07-29T05:01:00Z"
}

Failed · HTTP 200

{
  "request_id": "req_01JZEXAMPLE",
  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "real_person",
  "status": "Failed",
  "uri": "asset://asset-20260729-example",
  "failure": {
    "code": "InvalidImage",
    "message": "The image did not pass upstream validation."
  }
}

错误码

HTTP 状态	错误代码	说明	可重试
400	`invalid_request`	请求体、字段或参数值无效。	否
401	`invalid_api_key`	API Key 缺失、无效或已停用。	否
403	`resource_not_owned`	认证或素材不属于当前 API Key，或公开 ID 无效。	否
403	`capability_unavailable`	当前服务账号尚未开通私域人物素材权益。	否
409	`verification_pending`	仅在认证仍为 pending 时调用 POST /real-persons 返回；GET 认证状态仍返回 HTTP 200 和 status=pending。	是
410	`verification_expired`	GET 认证状态或 POST /real-persons 使用超过 30 分钟有效期的 verification_id。	否
413	`payload_too_large`	JSON 请求体超过 16 KB。	否
415	`unsupported_media_type`	POST 请求的 Content-Type 不是 application/json。	否
429	`rate_limit_exceeded`	当前 API Key 已达到调用限制。	是
500	`internal_error`	服务无法完成当前请求。	否
502	`upstream_error`	上游素材或认证服务返回错误。	是
503	`authentication_unavailable`	API Key 验证服务暂时不可用。	是
503	`service_unavailable`	素材 API 的服务端配置暂时不可用。	是

Error object

{
  "error": {
    "code": "invalid_request",
	    "message": "image_url is required.",
    "request_id": "req_01JZEXAMPLE",
    "retryable": false
  }
}

限流与追踪

每个 API Key 每小时最多 12 次创建类 POST 请求；GET 查询不计入。上游权益可能另有限制。达到限制时返回 429，并通过 Retry-After 指示建议等待秒数。

所有成功和错误响应都返回 request_id。向技术支持反馈问题时请提供该值，不要提供完整 API Key。

X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: <remaining>
X-RateLimit-Reset: <unix-seconds>
Retry-After: <seconds>

调用流程

1API 调用者使用 LaoZhang API Key 创建认证会话。
2将官方 verification_url 发给需要授权的真人本人。
3真人本人在官方 H5 页面确认授权并完成活体认证。
4从 callback_url 的 Location 查询参数读取 verification_id，并查询到 verified；pending 查询仍返回 HTTP 200。
5提交同一人物的清晰正面图片 URL。
6返回 Asset ID；查询到 Active 后才能用于视频生成。

限制与注意事项

API 调用无需 YingTu/Google 登录或 Cookie；真人本人仍需完成字节官方 H5 认证。
verification_id 是绑定当前 API Key 的不透明 ID；响应和回调不会返回 BytedToken 或 GroupId。
verification_url 不包含服务端长期 AK/SK，但仍是短期敏感的一次性链接；只交付给本人，不要记录或持久化。
pending 状态下提前 POST /real-persons 返回 HTTP 409；素材创建后，POST 和 GET 返回的公开 id 保持不变。
认证链接有效期为 30 分钟；过期返回 HTTP 410，必须重新创建会话。
服务账号未开通私域人物素材权益时返回 HTTP 403 capability_unavailable。

状态

Verification: requires_user_action → pending → verified
Expired verification: HTTP 410
Asset: Processing → Active | Failed