Referencia de REST API

API de recurso de persona real

El cliente de la API no inicia sesión en YingTu, pero la persona representada debe completar identidad, consentimiento y prueba de vida en el H5 oficial.

API de recurso de personaje virtualCrea un Asset ID reutilizable desde una única URL HTTPS pública.API de recurso de persona realCrea y consulta la verificación H5 oficial y genera un Asset ID autorizado.

Endpoint

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}

Autenticación

El cliente no inicia sesión en YingTu ni Google. Envía la API Key de LaoZhang mediante Authorization: Bearer <LAOZHANG_API_KEY>.

Cabecera	Obligatorio	Descripción
`Authorization`	Sí	API Key de LaoZhang mediante autenticación Bearer.
`Content-Type`	Solo POST	Las operaciones de creación usan application/json.

Solicitud

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

Campo	Obligatorio	Descripción
`callback_url`	Sí	URL HTTPS que se abre al terminar la verificación.
`language`	No	Idioma H5 oficial: zh, en o zh-Hant. Predeterminado: zh.

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

Campo	Obligatorio	Descripción
`verification_id`	Sí	Parámetro de ruta devuelto al crear la verificación.

POST /api/seedance-assets/real-persons

Campo	Obligatorio	Descripción
`verification_id`	Sí	Debe estar verified y pertenecer a la misma API Key.
`image_url`	Sí	URL HTTPS pública de una imagen frontal nítida de la misma persona.
`name`	No	Nombre del recurso, hasta 64 caracteres.

Solicitud de creación

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"
  }'

Ejemplo de respuesta

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"
}

Callback de verificación

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

result_code=10000 indica que terminó el flujo H5 oficial. Usa el verification_id de Location del callback para los GET y POST posteriores: un GET pending devuelve HTTP 200, un POST prematuro devuelve HTTP 409 y un ID caducado devuelve HTTP 410. El callback no expone BytedToken.

Idiomas de la página oficial de verificación

La documentación oficial solo enumera lng=zh, lng=en y lng=zh-Hant; el valor predeterminado es zh. Esta API aplica language al enlace devuelto.

Mapeo recomendado: zh→zh, en→en, ru/ja/ko/es→en. El chino tradicional puede usar zh-Hant. No se documentan páginas oficiales en español, ruso, japonés o coreano.

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

Ejemplos de código

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())

Consultar estado del recurso

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

Respuesta de estado

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."
  }
}

Errores

Estado HTTP	Código de error	Descripción	Reintentable
400	`invalid_request`	El cuerpo, un campo o un valor no son válidos.	No
401	`invalid_api_key`	La API Key falta, no es válida o está deshabilitada.	No
403	`resource_not_owned`	La verificación o el recurso no pertenece a esta API Key, o el ID público no es válido.	No
403	`capability_unavailable`	La cuenta de servicio no tiene habilitados los recursos privados de personas.	No
409	`verification_pending`	Solo lo devuelve POST /real-persons mientras la verificación está pending; consultar el estado por GET devuelve HTTP 200 con status=pending.	Sí
410	`verification_expired`	Un GET del estado o POST /real-persons usó un verification_id que superó los 30 minutos de vigencia.	No
413	`payload_too_large`	El cuerpo JSON supera los 16 KB.	No
415	`unsupported_media_type`	La solicitud POST no usa application/json.	No
429	`rate_limit_exceeded`	La API Key alcanzó su límite de solicitudes.	Sí
500	`internal_error`	El servicio no pudo completar la solicitud.	No
502	`upstream_error`	El servicio de recursos o verificación devolvió un error.	Sí
503	`authentication_unavailable`	La validación de la API Key no está disponible temporalmente.	Sí
503	`service_unavailable`	La configuración del servidor de la API de recursos no está disponible temporalmente.	Sí

Error object

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

Límites y seguimiento

Cada API Key admite hasta 12 solicitudes POST de creación por hora; las consultas GET no cuentan. Los derechos del proveedor pueden añadir límites. Una solicitud limitada devuelve 429 y Retry-After.

Todas las respuestas incluyen request_id. Inclúyelo al contactar con soporte, pero nunca envíes la API Key completa.

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

Flujo

1Crear una sesión de verificación con una API Key de LaoZhang.
2Enviar el verification_url oficial a la persona representada.
3La persona confirma el consentimiento y completa la prueba de vida en el H5.
4Leer verification_id de la query de Location del callback y consultarlo hasta obtener verified; un GET pendiente sigue devolviendo HTTP 200.
5Enviar la URL de una imagen frontal y nítida de la misma persona.
6Usar el Asset ID solo cuando su estado sea Active.

Límites y notas

Las llamadas API no requieren acceso a YingTu/Google ni Cookie; la persona debe completar la verificación H5 oficial de ByteDance.
verification_id es un ID opaco vinculado a la API Key actual. No se devuelven BytedToken ni GroupId.
verification_url no contiene el AK/SK permanente del servidor, pero sigue siendo un enlace temporal sensible. Entrégalo solo a la persona y no lo registres ni lo conserves.
POST /real-persons devuelve HTTP 409 mientras la verificación está pending. Tras crear el recurso, el id público es idéntico en las respuestas POST y GET.
El enlace dura 30 minutos. Una sesión caducada devuelve HTTP 410 y debe crearse de nuevo.
HTTP 403 capability_unavailable indica que falta el permiso de recursos privados de personas.

Estados

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