> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Библиотека активов Seedance 2.0 (Видео с единым персонажем)
> Используйте открытый API библиотеки активов icover.ai (продукт APIYI), чтобы загружать изображения и получать asset:// идентификаторы, а затем генерировать видео с единым персонажем через шлюз APIYI. Поддерживает работу в веб-интерфейсе без кода и пакетную интеграцию через REST API.
**icover.ai** — это субпродукт APIYI — онлайн-инструмент для тестирования генерации видео с помощью AI. Эта библиотека ассетов и её API помогают разработчикам и клиентам выпускать функции «видео с неизменным персонажем».
## Зачем нужна библиотека активов
При генерации видео с сохранением консистентности персонажа Seedance 2.0 **не принимает изображения-референсы, содержащие лица людей, напрямую** (фильтрация против deepfake). Сначала вы должны загрузить изображение как доверенный asset, получить ID asset `asset://xxx` и указать этот ID в запросе на генерацию видео.
Этот сервис берет загрузку на себя: просто **загрузите изображение → получите ID asset → сгенерируйте видео**. Есть два способа использования, и данные полностью общие между ними:
| Способ | Для кого лучше всего | Требования |
| ---------- | ------------------------------------------------------------ | -------------------------------------------- |
| **Web UI** | Всем, без кода | Просто зарегистрируйтесь и войдите в систему |
| **API** | Разработчикам, которым нужна программная пакетная интеграция | «Ключ Asset Library» |
**Общие данные**: для одной и той же учетной записи asset, загруженные через веб и через API, находятся в одной и той же библиотеке — asset, созданные через API, отображаются в веб-списке asset / архиве и в выборе reference-image в генераторе видео, а asset, созданные через веб, можно получить через API.
**Библиотека активов привязана к вашей учетной записи icover.ai, а не к KEY**: все Asset Library KEY, созданные в рамках одной учетной записи, эквивалентны и имеют доступ к одной и той же библиотеке — KEY это лишь учетные данные для вызова и не обеспечивает изоляцию. Asset изолированы по учетной записи; вы можете видеть и управлять только своими. Для изоляции и вариантов совместного использования между командами см. [FAQ](#faq) ниже.
**Два разных ключа — не путайте их**:
* **Ключ Asset Library** (создается на icover.ai, `sk-...`): только для endpoint библиотеки активов на этой странице (upload / ingest / query / delete).
* **APIYI SeeDance2 token** (создается на api.apiyi.com, `sk-...`, с включенной группой `SeeDance2`): только для endpoint генерации видео.
## Способ 1: Web UI (рекомендуется для новичков)
Откройте [страницу библиотеки ресурсов icover.ai](https://icover.ai/en/seedance-official/asset-library) и зарегистрируйтесь / войдите.
На вкладке «Загрузка виртуального аватара»: выберите изображения (поддерживается множественный выбор) → нажмите «Upload & Ingest».
* Группа ресурсов необязательна; система автоматически использует вашу группу по умолчанию. Сначала создайте группу, если хотите организовать resources по персонажам.
* Требования к изображениям: jpeg / png / webp / bmp / tiff / gif / heic; соотношение сторон 0.4–2.5; длина стороны 300–6000 px; размер каждого файла не более 30 MB.
Подождите около десяти с лишним секунд; когда статус станет «Active», скопируйте `asset://xxx` ID ресурса.
Перейдите в [icover.ai video generator](https://icover.ai/en/seedance-official): переключитесь в режим «Multimodal», задайте тип опорного изображения «Ресурс», выберите ваш ресурс и в prompt указывайте персонажа как «Изображение 1».
**Ресурсы реального человека (веб-версия)**: три шага на вкладке «Проверка реального человека» — 1) нажмите «Generate verification link», пусть актер отсканирует QR-код / откроет ссылку на телефоне, войдет в свою учетную запись Volcengine и пройдет проверку на живость; 2) нажмите «Query verification result», чтобы получить выделенную для актера группу ресурсов реального человека; 3) выберите эту группу и загрузите ресурсы (изображения / video / audio) — они пройдут проверку на согласованность лица, и вы получите ID `asset://`. Для одного и того же актера в разных образах используется та же группа, повторная проверка не нужна.
**Совет по согласованности персонажа**: для наилучших результатов поместите в одну группу ресурсов полный фронтальный снимок в полный рост и нейтральный крупный фронтальный план лица одного и того же персонажа.
## Способ 2: API (для разработчиков)
### Шаг 0: Создайте ключ Asset Library
После входа в icover.ai перейдите в Настройки → Asset Library KEY (`icover.ai/en/settings/apikeys`) и создайте KEY в формате `sk-...`.
Добавляйте его в каждый запрос asset-library:
```
Authorization: Bearer sk-your-asset-library-KEY
```
### Шаг 1: Загрузите файл и получите публичный URL
Файл ассета (изображение; ассеты реальных людей также поддерживают видео / аудио) сначала должен быть доступен по публичному URL. Выберите один из вариантов:
**A. У вас уже есть публичный URL** (ваш CDN / файловый хост) → перейдите к шагу 2.
**B. Загрузите в наше хранилище** (два вызова: запросить подписанный URL для загрузки → PUT файла):
```bash theme={null}
# 1. Request a presigned upload URL
curl -X POST https://icover.ai/api/storage/presign \
-H "Authorization: Bearer sk-your-asset-library-KEY" \
-H "Content-Type: application/json" \
-d '{"ext":"jpg","contentType":"image/jpeg"}'
# → { "code":0, "data": { "uploadUrl":"...", "publicUrl":"https://cdn.icover.ai/..." } }
# 2. PUT the file to uploadUrl (Content-Type must match the presign request)
curl -X PUT "the-uploadUrl-you-just-received" \
-H "Content-Type: image/jpeg" \
--data-binary @portrait.jpg
# Once it succeeds, publicUrl is your file's public address
# Same for video/audio: swap ext/contentType to mp4/video/mp4, mp3/audio/mpeg, etc.
```
### Шаг 2: Импортируйте ассет
```bash theme={null}
curl -X POST https://icover.ai/api/asset-library/assets \
-H "Authorization: Bearer sk-your-asset-library-KEY" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://cdn.icover.ai/uploads/seedance/xxx.jpg",
"label": "actor-A-front"
}'
# → Raw Volcengine response: { ..., "Result": { "Id": "asset-20260702xxxx-xxxxx" } }
```
* `groupId` необязателен: ваша группа по умолчанию используется / создается автоматически. Чтобы организовать по персонажу: сначала выполните `POST /api/asset-library/groups {"name":"actor-A"}`, чтобы получить ID группы, затем укажите здесь `"groupId":"group-xxx"`.
* `label` необязателен; он помогает идентифицировать ассеты в веб-интерфейсе.
### Шаг 3: Опрос до Active
Импорт выполняется асинхронно (примерно 13 секунд на изображение, без SLA). Выполняйте опрос по возвращенному Id:
```bash theme={null}
curl https://icover.ai/api/asset-library/assets/asset-20260702xxxx-xxxxx \
-H "Authorization: Bearer sk-your-asset-library-KEY"
# → Result.Status == "Active" means ready; "Failed" means re-upload
```
Рекомендуем опрашивать каждые 3 секунды; считайте отсутствие `Active` в течение 90 секунд тайм-аутом, требующим проверки.
### Шаг 4: Сгенерируйте видео с ID ассета (через APIYI)
Укажите ID ассета как `asset://` и вызовите APIYI с **вашим собственным APIYI SeeDance2 token** (не с ключом Asset Library):
```bash theme={null}
curl -X POST https://api.apiyi.com/seedance/api/v3/contents/generations/tasks \
-H "Authorization: Bearer sk-your-APIYI-token" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{"type":"text","text":"The character in Image 1 smiles at the camera, slow push-in, natural light"},
{"type":"image_url","image_url":{"url":"asset://asset-20260702xxxx-xxxxx"},"role":"reference_image"}
],
"ratio":"16:9","duration":5,"resolution":"720p"
}'
# Returns a task id; poll GET .../tasks/{id} until status=succeeded, then read content.video_url
```
Указывайте на ассет как "Image 1" в prompt — **не пишите в prompt исходный ID ассета**.
См. таблицы выбора модели, цен и разрешений в [Обзоре Seedance 2.0](/ru/api-capabilities/seedance2/overview); полные параметры генерации см. в [Video Generation API](/ru/api-capabilities/seedance2/video-generation). Полный рабочий end-to-end скрипт (загрузка → импорт → генерация → скачивание) см. в [Справочнике по Asset Reference](/ru/api-capabilities/seedance2/asset-reference).
### Полная справка по эндпоинтам
| Эндпоинт | Метод | Описание |
| ---------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/storage/presign` | POST | Запросить подписанный URL для загрузки файла `{ext?, contentType?}` |
| `/api/asset-library/groups` | POST / GET | Создать группу `{name, description?}` / вывести список ваших групп (включая группы реальных людей) |
| `/api/asset-library/assets` | POST / GET | Импортировать `{groupId?, imageUrl, label?, assetType?}` (assetType необязателен: `Image` / `Video` / `Audio`, по умолчанию Image) / вывести список ассетов (`?groupId=`, `?pageNumber=`, `?pageSize=` все необязательны; по умолчанию page 1, 100 на страницу, pageSize ограничен 100) |
| `/api/asset-library/assets/{id}` | GET / DELETE / PATCH | Проверить статус / удалить / обновить метку `{label}` |
| `/api/asset-library/real-person/sessions` | POST / GET | Начать верификацию реального человека `{name?}` → возвращает ссылку на верификацию H5 и учетные данные для запроса / вывести список ваших сеансов верификации |
| `/api/asset-library/real-person/sessions/{id}` | POST / PATCH / DELETE | Запросить результат верификации (при успехе возвращает GroupId группы ассетов реального человека) / переименовать `{name}` / удалить запись |
| `/api/asset-library/records` | GET | Ваши ассеты + архив верификации реального человека (источник данных веб-интерфейса) |
**Соглашения по ответам**: эндпоинты asset-library передают необработанный JSON Volcengine как при успехе, так и при ошибке (списки отфильтрованы по вашим ассетам); наши собственные ошибки возвращаются в виде обычного текста с префиксом `[client] ` (400/401/403/404/502); `records`, GET/PATCH/DELETE для `real-person/sessions` и ассет `PATCH` возвращают `{code, message, data}` JSON (код 0 = успех).
## Активы реального человека (полностью автоматизированный API)
Портреты реальных людей требуют, чтобы человек, которого снимают (актёр), один раз прошел **проверку живости**, закрепляя права на портрет на уровне источника. Весь процесс теперь полностью управляется через API; вкладка веб-интерфейса «Проверка реального человека» — это тот же процесс с интерфейсом:
### Шаг 1: Запустите сеанс верификации и получите ссылку H5
```bash theme={null}
curl -X POST https://icover.ai/api/asset-library/real-person/sessions \
-H "Authorization: Bearer sk-your-asset-library-KEY" \
-H "Content-Type: application/json" \
-d '{"name":"actor-A"}'
# → Raw Volcengine response: { "Result": { "BytedToken":"2026...", "H5Link":"https://ark.volcengine.com/..." } }
```
* Отправьте `H5Link` актёру, чтобы он **открыл её на телефоне** (или преобразуйте её в QR-код для сканирования). Он войдет в свою личную учетную запись Volcengine и завершит проверку живости. Освещение / угол камеры могут привести к неудачной попытке — просто повторите.
* `BytedToken` — это учетные данные для запроса; мы сохраняем их вместе с сеансом. `GET /api/asset-library/real-person/sessions` позволяет в любой момент просмотреть ваши сеансы (включая id / status / h5Link).
### Шаг 2: Получите результат после завершения актером
```bash theme={null}
curl -X POST https://icover.ai/api/asset-library/real-person/sessions/{session-id} \
-H "Authorization: Bearer sk-your-asset-library-KEY"
# Verified → { "Result": { "GroupId": "group-xxxx" } } ← the actor's dedicated real-person asset group
# Not yet → 404 NotFound. (raw Volcengine text; this is normal — query again after verification)
```
После получения `GroupId` статус сеанса становится `authorized`, а группа активов реального человека автоматически архивируется в вашей учетной записи (она также отображается в группе активов веб-интерфейса). **Примечание**: для ожидающей верификации возвращается тот же `NotFound`, что и для истекших учетных данных — различить эти два случая невозможно. Ссылка, долго остававшаяся без использования, может истечь; просто создайте новый сеанс.
### Шаг 3: Отправьте активы в группу реального человека
Тот же endpoint для загрузки, что и для виртуальных аватаров — просто передайте `groupId` группы реального человека. Поддерживаются изображения, видео и аудио:
```bash theme={null}
curl -X POST https://icover.ai/api/asset-library/assets \
-H "Authorization: Bearer sk-your-asset-library-KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "group-xxxx",
"imageUrl": "https://cdn.icover.ai/uploads/seedance/xxx.jpg",
"label": "actor-A-front-full-body",
"assetType": "Image"
}'
```
Затем опрашивайте до `Active` как обычно и создавайте видео с помощью `asset://` (Шаг 4 без изменений).
**Правила и форматы активов реального человека**:
* Одна группа реального человека содержит **только одного человека**; тот же актёр в разном стиле повторно использует ту же группу — повторная верификация не нужна.
* Каждая загрузка проходит **проверку согласованности лица** (видео сэмплируются каждую секунду, и каждый выбранный кадр должен пройти проверку). Профильный ракурс, несколько людей или размытый материал приведут к ошибке — используйте четкий фронтальный материал.
* Изображения до 30MB; видео mp4 / mov, 2–15 секунд, ≤50MB, соотношение сторон 0.4–2.5; аудио mp3 / wav, 2–15 секунд, ≤15MB.
## Примечания
**Считайте asset:// ID секретами**: assets изолированы на уровне этого service layer (защищены от просмотра списка и удаления), но Volcengine не может авторизовать доступ по ID — если ID утечет, другие вызывающие на том же канале смогут ссылаться на него в запросах на генерацию. См. [Часто задаваемые вопросы](#faq) ниже для полного описания модели владения и изоляции.
* **Срок действия Image URL**: preview URLs, возвращаемые query / list endpoints, — это временные адреса, действительные примерно 12 часов; не кэшируйте их надолго, сам asset ID является постоянным.
* **Лимиты запросов** (на уровне аккаунта Volcengine): status query — 100 QPS, ingest и другие операции — около 10 QPS. Управляйте concurrency и выполняйте повторные попытки при сбое.
* **Синхронизация статуса в Web UI**: после ingest через API, если статус ни разу не запрашивался, в web archive может отображаться «processing»; откройте страницу списка assets и нажмите «Refresh List», чтобы синхронизировать фактический статус.
Официальные материалы Volcengine (скопируйте в браузер): руководство по private asset library `volcengine.com/docs/82379/2333565`, onboarding assets реальных людей `volcengine.com/docs/82379/2315856`.
## ЧаВО
Прямые референсные изображения не могут содержать фотореалистичные человеческие лица (анти-deepfake фильтр их отклоняет). После загрузки портрета как доверенного ассета его ID `asset://` можно переиспользовать в любом числе задач генерации, сохраняя лицо и одежду персонажа единообразными между эпизодами и сценами — это идеально подходит для серийного контента, такого как анимационная драма, короткая драма и IP-персонажи. В кадре также могут появляться реальные люди: просто пройдите описанный выше поток верификации реального человека.
В одном предложении: **icover.ai изолирует ассеты; APIYI обеспечивает единый вызов — на стороне генерации проверяется только ID ассета, и наличия ID достаточно, чтобы сослаться на него.**
Она следует **аккаунту**. Базовая архитектура такова: все пользователи icover.ai используют единый аккаунт APIYI Volcengine, а библиотека ассетов принадлежит этому аккаунту; icover.ai добавляет на уровне сервиса слой **изоляции по каждому аккаунту** — каждый аккаунт может только получать список / запрашивать / удалять свои ассеты и не видит ID ассетов других пользователей.
KEY не обеспечивают изоляцию: несколько Asset Library KEY в рамках одного аккаунта эквивалентны и имеют доступ к одной и той же библиотеке. Если вам нужна изоляция ассетов (например, разделение данных по клиентам или направлениям бизнеса), **зарегистрируйте отдельный аккаунт icover.ai для каждой стороны** и создайте KEY в каждом из них — создание нового KEY в рамках одного и того же аккаунта ничего не изолирует.
Учитывайте границу безопасности: эта изоляция охватывает только получение списка / запрос / удаление, но Volcengine не может авторизовать по ID — как только ID `asset://` утечет, другие вызывающие стороны на том же канале смогут использовать его в запросах на генерацию. Считайте ID ассетов секретами.
Нет. Независимо от того, через веб-интерфейс или API, библиотека ассетов по сути **перенаправляет** все в официальные эндпоинты библиотеки ассетов Volcengine: контент image / video / audio напрямую отправляется в Volcengine на обработку, а обратно возвращается только ID `asset://`. Мы сами не храним и не логируем исходный контент ассетов — мы сохраняем только этот ID и его принадлежность аккаунту (это используется для описанной выше изоляции по каждому аккаунту).
Для ассетов с реальным лицом есть дополнительное жесткое требование: человек на фото должен лично пройти **проверку живого лица** (войдя в свой аккаунт Volcengine и пройти распознавание лица), что закрепляет право на портрет на источнике — никто другой не может пройти эту проверку вместо него. Полный поток см. в разделе «Реальные лица» выше.
**Использовать одну библиотеку совместно (рекомендуется, самый простой вариант)**: достаточно одного аккаунта + одного KEY. Централизованно управляйте ID ассетов в своей системе и распределяйте ID `asset://` по отделам — достаточно иметь ID, чтобы сослаться на него в запросе на генерацию видео (генерация видео использует собственный APIYI SeeDance2 token каждого отдела, и это не связано с KEY библиотеки ассетов). Вы также можете создать несколько KEY в рамках одного аккаунта и выдать их разным отделам (удобно для ротации / отзыва учетных данных) — эти KEY все равно будут иметь доступ к одной и той же библиотеке.
**Изолировать между отделами**: зарегистрируйте отдельный аккаунт icover.ai для каждого отдела, у каждого будут свои KEY. Обратите внимание, что изоляция охватывает получение списка / запрос / удаление — утекший ID ассета все равно можно будет использовать, поэтому не распространяйте ID без необходимости даже между отделами.
Да. Канал APIYI SeeDance2 использует официальный полнофункциональный `doubao-seedance-2-0-260128` — параметры модели, разрешения и длительности полностью совпадают с официальным предложением, без каких-либо урезаний. См. [Обзор Seedance 2.0](/ru/api-capabilities/seedance2/overview) для подробностей о модели и тарификации.
Нет, это не считается реальным человеком. Фотореалистичный портрет, сгенерированный AI и не имеющий реального прототипа (например, персонаж, созданный с помощью модели вроде Nano Banana), — это **виртуальный аватар**: он сразу проходит поток загрузки виртуального аватара без шага авторизации. Только фото **реального существующего человека** считается реальным лицом — для него загрузка НЕ означает авторизацию; канал загрузки виртуального аватара их отклоняет, а человек, которого снимают, должен пройти верификацию живости (см. раздел про реальные лица выше).
Три вида материалов персонажей:
| Тип материала | Примеры | Как использовать |
| ---------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Аниме / стилизованные персонажи | Аниме, мультфильмы, 3D-мультяшные персонажи | Нет фотореалистичного лица, обычно не блокируется: используйте напрямую общедоступный URL / Base64 референсного изображения, загрузка не требуется |
| Виртуальный аватар (AI-сгенерированный фотореалистичный портрет) | Сгенерирован моделью, такого человека не существует (см. пример ниже) | Используйте загрузку виртуального аватара на этой странице и указывайте ID `asset://` |
| Реальное лицо | Фотографии знаменитостей, моделей или вас самих | Используйте полностью автоматизированный поток API верификации реального человека; станет доступно после того, как этот человек пройдет проверку liveness |
Нет. Загрузка виртуального аватара полностью автоматическая — без ручной проверки, без шага авторизации: после загрузки система автоматически предварительно обрабатывает изображение, статус становится Active примерно через 13 секунд, и ID `asset://` сразу же можно использовать для генерации видео. Только ассеты с **реальным лицом** требуют, чтобы человек на фото прошел проверку живости (см. раздел про реальные лица выше).
Напрямую повторно использовать их нельзя. И библиотека ассетов Volcengine, и верификация реального человека **привязаны к базовому аккаунту**: ID `asset://`, полученный через другого провайдера, принадлежит аккаунту Volcengine этого провайдера, а обращение к нему через канал APIYI возвращает `asset not found`. Ассеты нужно заново загрузить через этот сервис.
* **Ассеты виртуального аватара**: их можно перенести программно массово — напишите скрипт, который повторно загрузит исходные изображения через API на этой странице, а затем обновите старые ID в своей системе на новые ID `asset://`. Мы рекомендуем хранить в своей системе слой сопоставления asset-ID: в ваших бизнес-данных сохраняются только внутренние ID, поэтому при смене провайдера позже нужно будет обновить только сопоставление.
* **Ассеты, верифицированные по реальному человеку**: верификация реального человека тоже привязана к аккаунту и **не может быть перенесена — требуется повторная верификация**: человек, которого снимают, должен снова пройти проверку живости (см. раздел про реальные лица выше).
* **Совет для продуктов для конечных пользователей**: при большом объеме существующих ассетов переносите виртуальные ассеты незаметно через фоновую задачу на сервере — пользователи ничего не заметят; для части с верифицированными реальными людьми предлагайте пользователям пройти повторную верификацию при обновлении системы или выпуске новой версии, так это воспринимается гораздо естественнее.
## Свяжитесь с нами
Если у вас возникнут какие-либо проблемы во время интеграции (сбои ingest, проверка реального человека, пакетная интеграция, заявки на production token и т. д.), не стесняйтесь обратиться — контактные данные указаны на главной странице [api.apiyi.com](https://api.apiyi.com).