Руководство по использованию API синхронизации губ PixVerse: загрузка, генерация, опрос и проверка

AI Overview

Что требуется от API синхронизации губ PixVerse?

Укажите один видеореференс и один источник речи. Видео может быть либо сгенерированным PixVerse source_video_id, либо загруженным video_media_id; речь может быть представленной в виде загруженного аудиофайла или в виде диктора TTS с текстовым сценарием.

Какой эндпоинт создаёт задачу синхронизации губ?

Отправьте запрос POST /openapi/v2/video/lip_sync/generate, указав ваш API-ключ, новый trace ID и одну допустимую комбинацию видео/аудио. При успешном создании задачи в ответе возвращается video_id, а не готовый файл.

Как узнать, что результат готов?

Выполняйте опрос эндпоинта GET /openapi/v2/video/result/{id} с использованием полученного video_id. В документации PixVerse статус 5 означает «в процессе генерации», а статус 1 — «успешно завершено»; только после получения статуса 1 используйте возвращаемый URL видео.

Можно ли использовать текст вместо аудиофайла?

Да. Выберите встроенный или пользовательский диктор TTS и укажите параметры lip_sync_tts_speaker_id и lip_sync_tts_content. Не комбинируйте этот способ с несвязанным audio_media_id в одном примере.

Выберите видео и голос перед вызовом API

Этот учебник по API синхронизации губ PixVerse ориентирован на конкретную задачу: нанести выбранную реплику на существующее движущееся лицо, получить асинхронный результат и оценить, пригодны ли движения губ для использования. Если исходный клип необходимо создать заранее, короткий кадр с говорящим человеком проще оценить, чем быстрый монтажный переход, поворот головы от профиля к анфасу или лицо, скрытое руками. Такой базовый клип можно создать с помощью workflow «из изображения в видео», генерации PixVerse или имеющегося у вас видеоматериала, использование которого разрешено.

Официальное руководство PixVerse по речи описывает два способа предоставления изображения. Клип, созданный через его API, уже имеет video_id, который передаётся как source_video_id. Внешний клип загружается через эндпоинт медиа и возвращает media_id, который передаётся как video_media_id. Эти идентификаторы не взаимозаменяемы. Записывайте происхождение каждого ID в собственном журнале задач, чтобы при повторной попытке не передать media_id загруженного файла в поле source_video_id.

Для речи выберите либо готовую запись с указанием audio_media_id, либо путь преобразования текста в речь (TTS) с параметрами lip_sync_tts_speaker_id и lip_sync_tts_content. Четыре возможные комбинации образуют матрицу 2×2: сгенерированное или загруженное видео, пересекающееся с записанной речью или диктором TTS. Образец голоса, использованный для создания пользовательского диктора, выполняет иную функцию по сравнению с финальной аудиозаписью, загружаемой для задачи синхронизации губ, даже если оба проходят этап загрузки медиа.

Изображения носят редакционный характер и иллюстрируют вымышленного взрослого спикера, а не являются выходными данными PixVerse или подтверждением точности синхронизации губ. Они демонстрируют важность чёткого изображения лица и неприкрытого рта при выборе исходного клипа.

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

Начните первое тестирование с умеренных требований: один видимый спикер, короткое предложение, чёткая речь и минимальное движение камеры. Руководство по речи и справочник по загрузке медиа на текущий момент указывают разные ограничения возможностей для загрузок синхронизации губ, поэтому не считайте скопированные размеры или продолжительность универсальным и постоянным правилом. Проверяйте актуальную документацию по конкретному эндпоинту и делайте начальный образец комфортно коротким. Кредиты API PixVerse отделены от членства в веб-приложении; убедитесь в наличии достаточного баланса перед запуском пакетной обработки.

Загрузка внешних медиа без путаницы с идентификаторами

Если у вас уже есть video_id, сгенерированный PixVerse, пропустите загрузку видео. В противном случае загрузите поддерживаемое внешнее видео через POST /openapi/v2/media/upload и сохраните возвращённый Resp.media_id как video_media_id. Голосовую дорожку также загрузите через тот же эндпоинт медиа и сохраните её Resp.media_id как audio_media_id. В документации PixVerse перечислены распространённые типы видео (MP4, MOV, WebM) и аудио (MP3, WAV, M4A, AAC); перед загрузкой уточните актуальные форматы и ограничения возможностей.

Называйте артефакты по назначению: speaker-base-v1.mp4, line-01-clean-v1.wav, а также запись задачи с соответствующими media ID. Убедитесь, что лицо остаётся видимым с начала речи, удалите лишние паузы и проверьте, обеспечивает ли исходный клип достаточное движение губ для новой реплики.

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

Для TTS пропустите загрузку готового аудио. Получите список голосов, выберите ID встроенного диктора или создайте пользовательский голос на основе отдельно загруженного образца с необходимыми разрешениями. Не предполагайте, что значение auto подходит для всех языков; сохраняйте фактически выбранный ID диктора. Для нескольких спикеров создавайте отдельные клипы и объединяйте их позже.

В руководстве по видео с родным аудио объясняется, почему голос, фоновая акустика и движение требуют совместной оценки. Получите согласие на использование реального лица или голоса человека и информируйте о синтетической речи там, где это уместно.

Отправьте один корректный запрос на генерацию

Официальный эндпоинт генерации: https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate. PixVerse требует указания API-KEY и нового Ai-trace-id для каждого API-запроса. Храните ключ на стороне сервера, а не в JavaScript-коде браузера или примерах в статьях. Повторное использование trace ID может вернуть предыдущий результат вместо запуска новой задачи, поэтому регистрируйте каждый ID вместе с соответствующими входными ID, версией сценария и ответом.Этот пример запроса использует исходное видео, сгенерированное с помощью PixVerse, и загруженный финальный аудиофайл. Замените примеры чисел на ID, возвращённые вашей собственной учётной записью; для данной статьи запрос не выполнялся.

curl -X POST 'https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate' \
  -H "API-KEY: $PIXVERSE_API_KEY" \
  -H "Ai-trace-id: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"source_video_id":123456,"audio_media_id":234567}'

Для внешнего видео замените source_video_id на video_media_id. Для преобразования текста в речь замените audio_media_id на оба параметра: lip_sync_tts_speaker_id и lip_sync_tts_content. Это альтернативные пути, а не четыре поля, которые следует заполнять одновременно. Обёртка ответа использует ErrCode, ErrMsg и Resp; при успешном создании задачи идентификатор Resp.video_id следует сохранить. Это не подтверждает, что воспроизводимый файл уже полностью сгенерирован.

Проверьте один тип video ID и один режим речи перед вызовом API; отклоните пустой скрипт TTS. Записывайте в лог возвращаемые кредиты без жёсткого кодирования цены. Свяжите каждую строку и ответ задачи с устойчивым идентификатором кадра (shot ID), например, с передачей между первым и последним кадром для обеспечения визуальной непрерывности.

Опрос задачи и обеспечение прослеживаемости результата

После создания задачи используйте GET /openapi/v2/video/result/{id} с возвращённым video_id. В документации PixVerse статус 5 означает «генерируется», а статус 1 — «успешно завершено». Успешный HTTP-ответ или ErrCode: 0 из вызова создания означают лишь принятие задачи, но не то, что движущийся результат прошёл вашу проверку. Когда статус равен 1, извлеките URL выходного файла из ответа и сохраните его копию в соответствии с вашей стандартной политикой управления ассетами до истечения срока действия URL или изменения прав доступа.

Статус 7 документирован как сбой модерации контента, а статус 8 — как сбой генерации. Оба случая следует рассматривать как остановленные задачи, а не опрашивать их бесконечно. В продакшен-версии опроса должен быть ограниченный интервал ожидания, экспоненциальный отступ (backoff) и надёжная запись последнего зафиксированного статуса. Если ваш воркер перезапускается, возобновите работу с сохранённого video_id, а не создавайте повторно платную задачу. Используйте новый trace ID только для намеренно нового запроса, но не имитируйте повторные попытки при медленной обработке задачи.

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

Сохраняйте читаемую запись с идентификаторами кадра (shot ID), видео и речи, trace ID, сгенерированным video_id, финальным URL и вердиктом проверки. Никогда не храните учётные данные в этом журнале проверки. В руководстве по рабочему процессу агента PixVerse описан общий цикл от брифа до создания кадра.

Проверка движения рта, аудио и границ монтажных склеек

Просмотрите финальный движущийся файл в нормальном темпе со звуком, затем — в замедленном темпе вокруг выбранных слогов. Выберите предложение, содержащее видимые билабиальные звуки, такие как p, b и m, и более длительный открытый гласный. Обратите внимание на закрытие рта перед этими согласными, правдоподобное раскрытие на гласном и начало и окончание речи без отвлекающего отставания. Это метод редакционной проверки, а не заявленный эталон или утверждение о замеренной доле успеха PixVerse.

Сравните результат с исходным материалом: направление взгляда, внешность, челюсть, освещение и зубы не должны резко меняться. Проверьте как крупный план, так и полный клип. Эти статичные кадры не являются результатом сравнения «до/после» в PixVerse.

Оригинальный редакционный кадр. Профильные ракурсы выявляют ошибки контура челюсти и губ, которые могут быть скрыты на фронтальном эскизе.

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

Независимый пример диалога Seedance для проверки движения губ и голоса в полном движении

Просмотрите всю фразу целиком и оцените движение губ, голос, движение головы и монтажные склейки; это не вывод PixVerse.

Используйте простую карточку принятия решения: «принять», если фраза разборчива, начинается в заданном такте, сохраняет идентичность говорящего и выдерживает просмотр в нормальном темпе; «исправить», если ошибочны только границы монтажной склейки или обрезка аудио; «отклонить», если форма рта, лица или синхронизация некорректны на всём протяжении. Одобрение должно основываться на движущемся файле, а не на статичном превью (poster). Отдельный пример рабочего процесса синхронизации губ может помочь сравнить общие практики проверки, однако элементы управления поставщика в нём не взаимозаменяемы с полями API PixVerse.

Диагностика на правильном уровне и организация доставки

Если API отклоняет запрос, проанализируйте пару «ответ — параметры». Проверьте, не перепутаны ли типы video ID, не использован ли ID голосового образца вместо финального аудио, не отсутствуют ли обязательные поля TTS или не переиспользован ли trace ID. Убедитесь в корректности авторизации, наличия кредитов, типа медиа, лимитов и одновременных запросов. Никогда не вставляйте ключ API в скриншоты для поддержки.Если задание выполнено успешно, но результат выглядит некорректно, смена конечной точки вряд ли исправит проблемы с геометрией исходного материала. Попробуйте использовать более устойчивый клип, чёткий голос, меньшее количество заслонений, более короткое высказывание и лицо, которое остаётся в кадре. Если сбой синхронизации происходит только на первом слове, проверьте аудиовступление и начальный кадр видео; если сбой возникает только при разрезе — скорректируйте границу монтажного перехода и фоновый тон помещения. Сохраняйте лучший одобренный дубль, перезапуская обработку только слабой реплики.

Seedance Agent применяется после получения результата API: объединяйте одобренный базовый клип, версию голоса, сгенерированный вывод, заметки по принятию и решение о монтаже; планируйте или заменяйте один кадр без полной пересборки всего ролика. Он может координировать организацию справочных материалов и их проверку, но не выполняет непротестированный вызов API PixVerse и не сертифицирует результат PixVerse. При комбинировании выходных данных от разных поставщиков сохраняйте прозрачность происхождения.

Заключение

Надёжный рабочий процесс API PixVerse для синхронизации губ предполагает выбор одного типа идентификатора видео и одного режима речи, загрузку только необходимых медиафайлов, отправку одного корректно оформленного запроса с новым идентификатором трассировки, ожидание завершения обработки возвращённого video_id и оценку фактического движущегося результата. Используйте актуальную документацию PixVerse как единственный авторитетный источник информации об ограничениях и расчётах, а принятие редактором отделяйте от создания задачи. Когда несколько одобренных реплик должны быть объединены в единый логичный финальный продукт, организуйте справочные материалы, проверку и финальный монтаж в Seedance Agent.