Описание нескольких изображений и референсного видео

На этой странице рассматриваются вопросы программного подключения «нескольких референсных изображений + одного референсного видео», включая границы возможностей, правила порядка, видео с глубиной, аудио, восстановление задач и оплату. Полная таблица полей тела запроса и готовые к копированию примеры см. в разделе Интерфейс генерации видео, добавление материалов в библиотеку — в разделе Интерфейсы библиотеки материалов.

Сначала выводы

• несколько изображений и одно референсное видео используют один и тот же массив content: каждое изображение занимает один элемент image_url, видео занимает один элемент video_url;
• у «видео с глубиной» нет отдельного поля deep_video: оно отправляется как обычное референсное видео, а в role используется reference_video;
• порядок массива — это порядок материалов. Рекомендуется явно указывать в промпте «изображение 1, изображение 2, изображение 3, референсное видео» и не полагаться на то, что сервер угадает порядок по именам файлов;
• generate_audio: false означает отключение аудиовыхода в сгенерированном результате; это не равно сохранению исходной звуковой дорожки входного референсного видео и не равно копированию входного аудио в итоговый ролик;
• точное количество изображений и видео, размер файлов, кодирование и ограничения параллелизма определяются каталогом моделей и фактическими ответами интерфейса; платформа не обещает единый набор ограничений для всех вариантов Seedance;
• если необходимо сохранить движения, ракурс камеры и монтажные склейки исходного ролика, референсное видео может служить только референсом для модели. В текущих публичных запросах нет универсального параметра «принудительно сменить план на N-й секунде», поэтому точную хронологию нельзя гарантировать только полями интерфейса.

I. Проверка возможностей текущей модели

Сначала прочитайте каталог моделей, видимый текущему Key:

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Каталог подтверждает только то, «видима ли модель и для каких интерфейсов она доступна»; именно data[].id — это значение model, которое нужно указать в запросе. Конкретные ограничения — количество референсных изображений, референсное видео, референсное аудио, соотношение сторон вывода, длительность и разрешение — определяются страницей сведений о модели и ошибками параметров, возвращаемыми интерфейсом; ограничения, не перечисленные в каталоге, платформа не будет угадывать за модель.

II. Добавление референсных материалов в библиотеку и ссылки на них

Сгенерированные изображения персонажей, многовидовые изображения персонажа и изображения сцен без людей не являются материалами с авторизацией реального человека — добавляйте их в библиотеку как обычные виртуальные материалы:

POST /api/v1/materials/groups
POST /api/v1/materials/assets
GET  /api/v1/materials/assets/{asset_id}

После того как статус материала становится Active, URL изображения в запросе видео можно заменить на:

asset://asset-20260911035115-etexu

При добавлении изображений по одному каждое получает собственный asset_id. Изображения персонажей и сцен можно поместить в одну виртуальную группу или создать отдельные группы; при отправке видео на них ссылаются через разные элементы content. Добавление в библиотеку, опрос и ответы с ошибками см. в разделе Интерфейсы библиотеки материалов.

При успешной отправке status обычно равен Processing, после завершения обработки становится Active; при сбое status равен Failed, а причину содержит error_message. Проверка выполняется асинхронно, платформа не обещает единого срока для всех изображений; программа должна запрашивать один и тот же asset_id и не отправлять материал повторно, пока он в состоянии Processing.

III. Несколько изображений + одно референсное видео

Приведённый ниже запрос описывает «1 изображение персонажа + 2 изображения сцен + 1 референсное видео». Индексы массива объясняются начиная с 1:

1. content[1] — изображение 1, изображение персонажа;
2. content[2] — изображение 2, изображение сцены 1;
3. content[3] — изображение 3, изображение сцены 2;
4. content[4] — референсное видео.

content[0] — текстовый промпт, он не входит в нумерацию изображений.

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    {
      "type": "text",
      "text": "图片1是人物身份参考，图片2和图片3是场景参考。参考视频用于动作、机位和镜头节奏参考；保持人物身份和场景关系一致。"
    },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://人物素材ID" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID1" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID2" } },
    { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://你的对象存储域名/reference-depth.mp4" } }
  ],
  "duration": 7,
  "resolution": "720p",
  "ratio": "9:16",
  "generate_audio": false,
  "watermark": false
}

После успешного создания возвращается ID задачи; в дальнейшем запрашивайте только эту задачу:

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Если ответ явно сообщает, что текущая модель не поддерживает библиотеку материалов, используйте публичный HTTPS-адрес изображения, поддерживаемый этой моделью, или смените модель; не обходите проверку материалов. Полные примеры ответов на создание и запрос см. в разделе Интерфейс генерации видео.

IV. Границы референсного видео, звука и видео с глубиной

Референсное видео — не точная управляющая дорожка

Видео с глубиной в градациях серого в структуре публичного интерфейса остаётся обычным reference_video. Если в сведениях о текущей модели отдельно не заявлена поддержка управления глубиной, платформа не интерпретирует значения градаций серого как ограничения глубины и не гарантирует строгого копирования глубины, траектории движений или монтажных склеек исходного видео.

Референсное видео помогает модели понять движения, ракурс камеры, композицию и ритм, но итоговый ролик всё равно генерируется моделью заново. В текущих публичных запросах нет универсальной дорожки таймкодов или поля принудительной смены плана; если нужна смена плана примерно в определённый момент, её можно только описать в промпте и проверить итоговый ролик после генерации; если требуется покадровая точность, её следует обеспечивать на этапе внешнего монтажа или композитинга.

Входная звуковая дорожка и generate_audio

Если референсное видео содержит исходную звуковую дорожку, то, будет ли модель её считывать, зависит от реализации референсного видео в текущей модели. Однозначный смысл generate_audio: false — отключение аудиовыхода сгенерированного результата; он не гарантирует копирование звуковой дорожки входного видео и не гарантирует использование входной дорожки как отдельного референсного аудио.

• если цель — «сгенерировать видео без звука», можно передать generate_audio: false;
• если цель — «сохранить звук исходного ролика», не полагайтесь только на это поле: после скачивания итогового ролика обработайте его собственным процессом аудиовидеомонтажа или выберите конфигурацию, в которой сведения о модели явно поддерживают референсное аудио и выходное аудио;
• если в сведениях о модели не заявлена поддержка референсного аудио, не передавайте дополнительно reference_audio.

V. Ограничения, по которым сейчас нельзя дать единую гарантию

О том, поддерживает ли текущая группа этот набор запросов

Группа вызовов и группа библиотеки материалов — два разных понятия; нельзя определять поддержку нескольких изображений или референсного видео только по названию группы в консоли. Фактический порядок проверки таков:

1. выбранная модель существует в /v1/models;
2. сведения о модели явно разрешают референсные изображения и референсное видео;
3. статус материала, на который делается ссылка, — Active;
4. интерфейс создания возвращает queued, что означает, что запрос принят;
5. если итоговый статус failed, прочитайте error.code и error.message, чтобы определить проблему комбинации или материала.

Платформа не будет незаметно переключать модель, не поддерживающую референсное видео, на другую модель, чтобы избежать непредвиденных расходов и результатов.

VI. Восстановление задач, ограничение частоты запросов, идемпотентность и оплата

Запрос и восстановление

Получив id от интерфейса создания, необходимо сразу его сохранить; при обрыве сети, когда ID задачи уже получен, запрашивайте только исходную задачу. В текущем публичном интерфейсе нет универсального способа найти задачу по «промпту + материалам + параметрам»; если соединение прервалось до возврата ответа о создании и ID задачи отсутствует, платформа не может гарантировать восстановление исходной задачи только по телу запроса. Поэтому вызывающая сторона должна сохранять бизнес-запрос в собственной базе данных и немедленно записывать ID задачи после получения ответа о принятии.

Опрос, ограничение частоты запросов и хранение

Платформа не публикует единые для всех групп вызовов значения параллелизма и частоты запросов на каждый API Key; клиент должен соблюдать ответы 429 и использовать опрос с нарастающей задержкой, рекомендуется запрашивать раз в 5–15 секунд. После генерации итогового ролика его следует как можно скорее скачать или пересохранить; нельзя считать возвращённый URL постоянным адресом. Если задача всё ещё доступна для запроса, но metadata.url истёк, сначала запросите исходную задачу повторно; если ссылку восстановить невозможно, публичный интерфейс не гарантирует повторную генерацию того же адреса.

Идемпотентность и номер запроса клиента

Текущий публичный интерфейс видео не предоставляет официального идемпотентного поля, управляемого пользователем, и не гарантирует, что пользовательский номер запроса позволит дедуплицировать по телу запроса. Вызывающая сторона может использовать собственный бизнес-номер запроса для записи связей, но не должна считать его идемпотентным ключом, который платформа обязательно распознает; на стороне платформы надёжная основа для восстановления появляется только после возврата ID задачи.

Смена API Key

Принадлежность задач и материалов определяется учётной записью платформы; после смены Key в рамках одной учётной записи можно продолжать запрашивать исходную задачу, повторяя запрос с Key, использованным при создании задачи. Если новый Key принадлежит другой учётной записи, запрос вернёт 401 или 404; в этом случае не создавайте задачу заново, чтобы обойти сбой запроса.

Оплата, сбои и возвраты

Плата за добавление материалов в библиотеку, проверку, скачивание референсного видео и генерацию видео зависит от текущей модели и ценовой конфигурации платформы. Видеозадачи рассчитываются по фактическому использованию при завершении; успешное создание не влечёт предварительного удержания средств, и после завершения в счёте появляется только одна запись о фактическом списании. Перед отправкой проверяется, покрывает ли баланс оценку; при недостатке средств сразу возвращается понятное сообщение, и задача не создаётся. Данные о стоимости появляются в ответе на запрос только после завершения расчёта:

• ответ о создании означает лишь то, что задача принята; на этом этапе данных о расчёте нет, поэтому поля списания не возвращаются — не определяйте стоимость по ответу о создании;
• ответ на запрос после завершения расчёта задачи возвращает usage: usage.total_tokens — количество видеотокенов, оплачиваемых в этот раз (вышестоящий сервис сообщает только одно число токенов, которое по правилам биллинга платформы записывается в usage.prompt_tokens, а usage.completion_tokens равно 0), usage.quota — потраченные баллы, usage.amount — сумма в юанях, пересчитанная из тех же баллов (usage.currency всегда CNY);
• ошибка проверки параметров (HTTP 400 / 403) означает, что запрос не принят, и плата за задачу генерации не возникает;
• после возврата ID задачи взимание платы и возврат средств при сбое регулируются правилами оплаты этой модели и платформы;
• правила списания и возврата при сбое проверки, сбое генерации и отмене задачи нельзя выводить только из статуса задачи;
• для сверки расходов сохраните ID задачи, ID модели, время создания и учётную запись, к которой относится API Key, и сверьте usage.quota / usage.amount из ответа на запрос со счётом в консоли либо обратитесь в поддержку платформы.

VII. Типичные ответы с ошибками

{
  "error": {
    "code": "invalid_parameter",
    "message": "当前模型不支持参考视频，或参考素材数量超出限制",
    "type": "invalid_request_error",
    "param": "content"
  }
}