API говорящего аватара: как превратить портрет и аудио в говорящий клип

Модель spicyapi/talking-avatar-v1/talking-avatar превращает один портрет и 3–60 секунд речи в MP3 или WAV в говорящий MP4. Запись задаёт слова и тайминг, портрет — лицо и сцену. Стоимость — 0,018 $ за каждую возвращённую секунду с округлением вверх и минимумом в три секунды; реплика в 4–5 секунд рендерится примерно за минуту (60-секундная запись занимает дольше). Результат компактный, около 0,2 мегапикселя при 25 кадр/с, поэтому он подходит для карточки, ленты или окна чата, но не для HD-ведущего на весь экран. Если нужен HD или более длинное аудио, посмотрите вариант Kling Avatar 2.0 в конце. Настоящий результат можно послушать на странице модели.

Подготовьте портрет и запись

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

• одно чёткое лицо, примерно анфас, ровное освещение, голова и плечи;
• без рук, волос, солнцезащитных очков или микрофона перед ртом;
• JPEG, PNG или WebP, не более 10 МБ, с запасом вокруг подбородка и волос для вашего итогового плеера.

Запись — это MP3 или WAV не более 90 МБ длительностью 3–60 секунд, с одним голосом, без музыки и перекрывающихся говорящих. Уберите случайную тишину, но не первое и не последнее слово: тишина входит в оплачиваемую длительность. Файлы вне диапазона 3–60 секунд отклоняются до любого списания.

Иллюстрация к этапу подготовки, а не кадр Talking Avatar.

Полей script, voice_id и language нет. Для другого языка запишите или сгенерируйте другой аудиофайл и используйте тот же портрет. Если у вас уже есть видео движущегося ведущего и нужно только заменить речь, воспользуйтесь процессом синхронизации губ.

Входные данные

Полей для разрешения, частоты кадров, длительности и камеры нет. Фото 16:9 возвращается в размере 640×352, а портрет 3:4 — 400×544.

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

Сколько это стоит и почему расчёт составляет 1,08 $

Списывается возвращённая длительность, округлённая вверх до целых секунд, не менее трёх секунд:

Расчёт и резерв, который блокируется при создании задачи, соответствуют потолку в 60 секунд: 1,08 $, какой бы ни была длина вашего аудио. Когда клип готов, итоговая сумма пересчитывается по фактической длительности, а остаток освобождается; при сбое задачи резерв освобождается полностью. До этого момента резерв учитывается в вашем балансе и лимитах расходов, поэтому почти пустой баланс или жёсткий лимит могут заблокировать даже 12-секундный клип. Сам расчёт ничего не резервирует.

Сначала попробуйте в Playground

1. Откройте страницу модели Talking Avatar и оставайтесь на вкладке Playground в режиме Form. Для запуска войдите в аккаунт с пополненным балансом; цена отображается после входа.
2. В поле Input image перетащите портрет Мары или вставьте ссылку через Add URL.
3. В поле Input audio добавьте MP3 или WAV так же. Загрузка файла надёжнее ссылки.
4. При желании введите пару слов о выражении в Prompt (calm and welcoming), добавьте Mask для группового портрета или задайте Seed, чтобы сравнить две записи.
5. Запустите и воспроизведите результат со звуком в том размере, в котором вы будете его показывать.

Playground отправляет тот же запрос, что и API, поэтому портрет и запись, которые работают здесь, будут работать и в коде. Если здесь трудно разглядеть движение губ, исправьте исходные файлы, прежде чем писать код.

Затем вызовите из кода

Установите Python SDK (pip install spicyapi), задайте SPICY_API_KEY и запустите следующий код. Создание задачи платное, а резерв — это описанный выше потолок 1,08 $.

import shutil
import urllib.request
import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

portrait = client.upload_file("./mara.png")      # local files become spicy:// URIs
speech = client.upload_file("./mara-intro.mp3")

task = client.create_task(
    model="spicyapi/talking-avatar-v1/talking-avatar",
    input_data={
        "image_url": portrait["uri"],
        "audio_url": speech["uri"],
        "prompt": "calm and welcoming",
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")

url = output_assets(final)[0]["url"]
request = urllib.request.Request(url, headers={"User-Agent": "avatar-example/1.0"})  # default Python clients can get a 403
with urllib.request.urlopen(request, timeout=60) as response, open("avatar.mp4", "wb") as target:
    shutil.copyfileobj(response, target)
print("Saved avatar.mp4")

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

Или поручите запуск агенту

Если клипы должен делать ассистент, дайте ему CLI или MCP-сервер. Оба показывают цену и просят подтверждения перед платным вызовом. Skill добавляет инструкции поверх любого из них.

• CLI. spicyapi запускает одну задачу из терминала (npx @spicyapi/cli работает без установки):

``bash spicyapi files upload ./mara.png # prints a spicy:// URI; repeat for the audio spicyapi tasks create --model spicyapi/talking-avatar-v1/talking-avatar \ --input-file input.json --wait ``

input.json содержит тот же объект input, что и выше, с двумя URI spicy://.

• MCP-сервер. Добавьте MCP-сервер своему ассистенту и попросите: "Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar." Он вызовет spicyapi_upload_file, затем spicyapi_task_create (который остановится, чтобы вы подтвердили цену), затем spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill устанавливает Agent Skill, который учит ассистента для программирования читать актуальную схему и повторно использовать ключи идемпотентности, а не гадать. Сам он задачи не запускает, поэтому используйте его вместе с CLI или MCP.

Исправляйте проблемы в источнике

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

Иллюстрация к проверке узнаваемости; напечатанные портреты — сконструированная графика, а не кадры аватара.

Правила контента и когда выбрать другую модель

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

Kling Avatar 2.0 тоже принимает портрет и аудио, в 720p (0,0512 $ за секунду) или 1080p (0,1024 $ за секунду), с клипами до примерно пяти минут. Это модель с фильтрацией: откровенные портреты отклоняются, поэтому она подходит для клипов ведущих и брендов, а не для персонажей, ориентированных на взрослых. Выбирайте Talking Avatar v1 для коротких и недорогих клипов размером с карточку, а Kling Avatar 2.0 — когда клип должен выглядеть чётко на весь экран или идти дольше минуты.