> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API ассетов реальных людей и виртуальных персонажей Seedance

> Как пройти верификацию реального человека, создать ассеты реальных людей и виртуальных персонажей, проверить их статус и использовать в видеозадачах Seedance с API-ключом LaoZhang API.

Seedance не принимает обычные фотографии с лицами реальных людей, поэтому постоянный человек или персонаж попадает в видео через ассет. Когда ассет получит статус `Active`, добавьте его URI `asset://...` в [видеозадачу Seedance](https://docs.laozhang.ai/ru/api-capabilities/seedance2-video-generation.md).

| Параметр | Значение |
| - | - |
| Базовый URL | `https://yingtu.ai` |
| Аутентификация | API-ключ LaoZhang API как Bearer-токен; сессия YingTu или Google и отдельный API-ключ YingTu не нужны |
| Ассеты виртуальных персонажей | Доступны: многоразовый Asset ID создаётся из одного публичного HTTPS-изображения |
| Ассеты реальных людей | Доступны: перед созданием Asset ID нужно пройти официальную H5-проверку согласия и живого присутствия |
| Получение статуса ассета | Доступно: запрашивайте по публичному `id`, пока ассет не перейдёт в `Active` или `Failed` |
| Генерация видео Seedance | Доступна: передайте URI `asset://...` в видеозадачу как `reference_image` |
| Полный справочник | Поля запросов, объекты ответов, коды ошибок и лимиты описаны в справочниках YingTu: [API ассетов реальных людей](https://yingtu.ai/en/docs/seedance-assets/real-person) и [API ассетов виртуальных персонажей](https://yingtu.ai/en/docs/seedance-assets/virtual-human) (на английском) |

> [!WARNING]
>
> **Человек, которого представляет ассет, должен сам пройти официальную H5-проверку.**
>
> * Проверка включает подтверждение личности, согласие и проверку живого присутствия.
> * Для виртуального персонажа, основанного на реальном человеке, также нужны права на внешность, голос, имя, товарный знак и использование.

## Аутентификация

Все эндпоинты ассетов принимают API-ключ LaoZhang API:

```http theme={null}
Authorization: Bearer <LAOZHANG_API_KEY>
Content-Type: application/json
```

Сессия YingTu, сессия Google и cookie не нужны: по API-ключу проверяются аккаунт LaoZhang API и доступный баланс. Записи о верификации и ассетах привязаны к API-ключу, которым они созданы. Поэтому последующие запросы статуса и создание ассета реального человека отправляйте с тем же ключом.

Храните ключ в переменной окружения на сервере. Никогда не вставляйте ключ целиком в код для браузера, URL, логи или обращения в поддержку. Примеры ниже читают его из `LAOZHANG_API_KEY`:

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_API_KEY"   # замените на свой API-ключ LaoZhang API
```

## Оплата

Тарифицируются ли отдельно вызовы верификации и ассетов, видно на [странице цен в консоли](https://api.laozhang.ai/account/pricing) и в [журнале вызовов](https://api.laozhang.ai/log). Генерация видео с ассетом — это обычная задача Seedance, она оплачивается так же, как любая другая задача Seedance; подробности — в разделе об оплате и ценах [руководства по Seedance](https://docs.laozhang.ai/ru/api-capabilities/seedance2-video-generation.md).

## Эндпоинты

Ассеты виртуальных персонажей:

| Метод | Путь | Назначение |
| - | - | - |
| `POST` | `/api/seedance-assets/virtual-humans` | Создать ассет виртуального персонажа из публичного HTTPS-изображения |
| `GET` | `/api/seedance-assets/virtual-humans/{id}` | Получить статус обработки ассета |

Ассеты реальных людей:

| Метод | Путь | Назначение |
| - | - | - |
| `POST` | `/api/seedance-assets/real-persons/verifications` | Создать сессию официальной H5-верификации |
| `GET` | `/api/seedance-assets/real-persons/verifications/{verification_id}` | Получить статус верификации |
| `POST` | `/api/seedance-assets/real-persons` | Создать ассет реального человека после верификации |
| `GET` | `/api/seedance-assets/real-persons/{id}` | Получить статус обработки ассета |

## Создание ассета виртуального персонажа

Ассеты виртуальных персонажей подходят для цифровых людей, персонажей бренда, виртуальных ведущих и корпоративных представителей. Передайте одно публичное HTTPS-изображение, которое скачивается без аутентификации. URL приватных и loopback-адресов, а также изображений за cookie или входом в аккаунт отклоняются.

```bash theme={null}
curl --request POST \
  --url https://yingtu.ai/api/seedance-assets/virtual-humans \
  --header "Authorization: Bearer $LAOZHANG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "image_url": "https://cdn.example.com/avatar.webp",
    "name": "brand-avatar"
  }'
```

Успешный ответ содержит публичный `id` для запроса статуса, `uri` ассета и начальный статус:

```json theme={null}
{
  "request_id": "req_01JZEXAMPLE",
  "id": "ast_eyJvcGFxdWUiOiJleGFtcGxlIn0",
  "object": "seedance.asset",
  "kind": "virtual_human",
  "name": "brand-avatar",
  "status": "Processing",
  "uri": "asset://asset-20260729-example"
}
```

> [!NOTE]
>
> По `id` запрашивайте статус ассета у YingTu, а `uri` передавайте в видеозадачу Seedance. Сохраняйте оба значения в точности как получили; не собирайте и не декодируйте внутренние идентификаторы по примерам.

## Создание ассета реального человека

Для ассета реального человека перед созданием добавляется шаг согласия и проверки живого присутствия. Запустить этот процесс можно из своего продукта, но `verification_url` нужно передать самому человеку, которого представляет ассет.

**1. Создайте сессию верификации**

Вызовите `POST /api/seedance-assets/real-persons/verifications` и передайте HTTPS-адрес в `callback_url`.

Необязательный параметр `language` принимает:

* `zh` (по умолчанию)
* `en`
* `zh-Hant`

**2. Передайте ссылку человеку для верификации**

Безопасно передайте одноразовую ссылку `verification_url` этому человеку. Она действует 30 минут; не пишите её в логи и не храните долго.

**3. Получите результат верификации**

Возьмите `verification_id` из callback и запросите статус. Пока верификация не завершена, ответ всё равно приходит с HTTP 200. Создавайте ассет только после статуса `verified`.

**4. Создайте ассет реального человека и проверьте его**

Передайте публичный HTTPS-URL чёткого фронтального снимка того же человека. Запрашивайте возвращённый публичный `id`, пока ассет не перейдёт в `Active`.

Создание сессии верификации:

```bash theme={null}
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"
  }'
```

Создание ассета реального человека после верификации:

```bash theme={null}
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"
  }'
```

> [!WARNING]
>
> Обычный `image_url` не заменяет процесс создания ассета реального человека. Если нужно сохранить личность или внешность реального человека, сначала пройдите верификацию и получите URI ассета со статусом `Active`.

## Проверка статуса ассета

Для обоих типов ассетов используется публичный `id` из ответа на создание. Например:

```bash theme={null}
curl --request GET \
  --url https://yingtu.ai/api/seedance-assets/virtual-humans/ast_eyJvcGFxdWUiOiJleGFtcGxlIn0 \
  --header "Authorization: Bearer $LAOZHANG_API_KEY"
```

| Статус | Значение | Что делать |
| - | - | - |
| `Processing` | Ассет обрабатывается на стороне сервиса | Запросите статус позже; в видеозадаче ассет пока использовать нельзя |
| `Active` | Ассет готов | Добавьте его URI `asset://...` в задачу Seedance |
| `Failed` | Обработка не удалась | Прочитайте `failure`, исправьте изображение или проблему с правами и создайте ассет заново |

Неудавшийся ассет тоже может вернуть HTTP 200 — со `status`, равным `Failed`, и объектом `failure`. Поэтому один HTTP-статус не доказывает, что ассет готов.

## Ассет в видеозадаче Seedance

Когда ассет реального человека или виртуального персонажа перейдёт в `Active`, добавьте его полный URI `asset://...` в `content` с ролью `reference_image`. Видео генерируется через [API генерации видео Seedance](https://docs.laozhang.ai/ru/api-capabilities/seedance2-video-generation.md) в LaoZhang API:

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "Реальный ведущий представляет продукт, а рядом ему отвечает виртуальный ведущий. Камера медленно наезжает."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-real-person-example"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-virtual-human-example"
      },
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "duration": 4,
  "resolution": "720p",
  "watermark": false,
  "generate_audio": true
}
```

Домены отвечают за разные шаги, и оба принимают API-ключ LaoZhang API:

* создание и проверка ассетов — `https://yingtu.ai/api/seedance-assets/...`;
* создание видеозадачи и получение результата — `https://api.laozhang.ai/seedance/api/v3/...`.

## Лимиты, ошибки и критерий готовности

* Каждый API-ключ может отправить до 12 `POST`-запросов на создание в час. `GET`-запросы статуса ассета в этот лимит не входят. При `429` подождите время из заголовка `Retry-After`.
* Ссылка на верификацию реального человека действует 30 минут. Истёкшая сессия возвращает `410 verification_expired`, её нужно создать заново.
* Попытка создать ассет реального человека, пока верификация не завершена, возвращает `409 verification_pending`.
* `403 capability_unavailable` означает, что у аккаунта нет отдельного права на портретные ассеты, и замена изображения не поможет. Чтобы запросить доступ, напишите в поддержку на [hi@laozhang.ai](mailto:hi@laozhang.ai) или в Telegram ([@laozhang\_cn](https://t.me/laozhang_cn)) и укажите `request_id`.
* Каждый успешный ответ и каждая ошибка содержат `request_id`. Указывайте его, когда обращаетесь в поддержку, но никогда не присылайте API-ключ целиком.
* Интеграция готова, когда запрос статуса возвращает `Active`, а задача Seedance с полученным URI `asset://...` завершается успешно.

## Частые вопросы

### Подойдёт ли фото реального человека как референсное изображение?

Нет. Volcengine не принимает референсные изображения и видео с лицами реальных людей для моделей Seedance 2.0 и Seedance 2.5, а модерация контента на стороне модели блокирует такие запросы.

Если в видео должен появиться конкретный человек, он проходит верификацию, а вы создаёте ассет реального человека (см. раздел «Создание ассета реального человека»). Если нужен просто реалистичный персонаж, а не определённый человек, создайте ассет виртуального персонажа (см. раздел «Создание ассета виртуального персонажа»).

В обоих случаях дождитесь статуса `Active` и передайте URI `asset://...` как `reference_image`.

### Что выбрать: ассет виртуального персонажа или реального человека?

Это зависит от того, должен ли в видео быть конкретный реальный человек. Цифровым людям, персонажам бренда и виртуальным ведущим, которые не представляют реальную личность, достаточно ассета виртуального персонажа из одного публичного HTTPS-изображения.

Чтобы сохранить личность и внешность реального человека, нужен ассет реального человека. Этот человек должен сам пройти официальную H5-проверку согласия и живого присутствия в течение 30 минут, пройти её за него нельзя.

Для виртуального персонажа, основанного на реальном человеке, всё равно нужны права на внешность, голос, имя и использование.

### Останутся ли ассеты доступны после смены API-ключа?

Нет. Записи о верификации и ассетах привязаны к создавшему их API-ключу. Запрос статуса или создание ассета реального человека по этой верификации с другим ключом вернёт `403 resource_not_owned`. Прежде чем менять или отключать ключ, убедитесь, что эти ассеты больше не нужно запрашивать (см. раздел «Аутентификация»).

## Связанные материалы

* [Полный справочник API ассетов реальных людей](https://yingtu.ai/en/docs/seedance-assets/real-person) (на английском)
* [Полный справочник API ассетов виртуальных персонажей](https://yingtu.ai/en/docs/seedance-assets/virtual-human) (на английском)
* [API генерации видео Seedance](https://docs.laozhang.ai/ru/api-capabilities/seedance2-video-generation.md)
* [Как просматривать журнал вызовов](https://docs.laozhang.ai/en/faq/call-logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.