01
Несовпадение пропорций обходится дорого и незаметно
Если опора 1:1, а вы просите клип 16:9, эндпоинт вынужден добавлять поля, обрезать или растягивать. Приведите опору к запрашиваемому aspect_ratio или resolution до отправки.
Руководство по интеграции
Оживите кадр, которому вы уже доверяете.
«Изображение в видео» убирает самую трудную переменную — как выглядит сцена — и заменяет её более узкой: как она должна двигаться. Опорный кадр делает основную работу, поэтому слабую опору текст запроса не спасает.
Задача
Опорный кадр решает большую часть результата
Эндпоинты движения наследуют из первого кадра всё: композицию, свет, пропорции, артефакты. Мягкая или неудачно кадрированная опора даёт мягкий и неудачно кадрированный клип — по видеотарифу.
02
Некоторые эндпоинты принимают и финальный кадр
Там, где объявлен last_image_url, обе опоры задают определённое начало и конец вместо свободного дрейфа. Там, где он не объявлен, его отправка — это 400.
03
Поля движения есть только там, где они объявлены
movement_amplitude, camera_fixed, fps и duration_seconds появляются от эндпоинта к эндпоинту, и схема отмечает, какие из них меняют тариф. Общего словаря движения снизу не существует.
Подход
Сначала зафиксируйте кадр, за движение заплатите один раз
Работу со статикой делайте на эндпоинте изображений, где итерация стоит центы, зафиксируйте кадр и только потом платите за движение. Подтверждённая загрузка spicy:// сохраняет опору побайтово одинаковой между попытками, поэтому повтор стартует ровно с тех же пикселей.
Тело — это вызов создания с полем изображения. Отслеживание ничем не отличается от любой другой медиазадачи.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/image-to-video",
"input": {
"prompt": "Slow push-in, fabric moving in a light breeze",
"image_url": "https://example.com/reference.png",
"duration_seconds": 5,
"resolution": "720p"
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Контракт
Что стоит зафиксировать сразу
| Поле или заголовок | Значение или предел |
|---|---|
| image_url · last_image_url | declared per endpoint |
| POST /api/v1/jobs/retry | new task · source record untouched |
| state | queued · running · succeeded · failed · expired |
| audio / video upload | ≤ 100 MiB · ≤ 600 s |
Проведите по горизонтали, чтобы увидеть все столбцы.
Интеграция
От первого вызова до продакшена
- 01Подготовьте или загрузите опорный кадр в тех пропорциях, в которых собираетесь рендерить.
- 02Прочитайте в схеме image_url, duration_seconds, resolution и объявленные поля движения.
- 03Оцените, отправьте с Idempotency-Key и адресом обратного вызова и сохраните taskId вместе с опорой.
- 04По конечному обратному вызову скачайте output.assets и оставьте опору рядом с клипом, чтобы повтор был возможен.
Применимость
Когда этот путь подходит
Выбирайте, если
- Художественное решение уже зафиксировано в кадре, и нужно движение без пересъёмки сцены.
- Один и тот же персонаж или товар должен выглядеть одинаково в каждом клипе.
Ищите другое, если
- Сцены ещё нет. Итерации по статике дешевле итераций по клипам на порядок.
- Нужна непрерывность на множестве планов. Эти эндпоинты возвращают короткие клипы, по одному плану за раз.
Проверки
Что вы можете проверить сами
Ссылки ведут себя одинаково везде
HTTPS-адреса, подтверждённые загрузки spicy:// и встроенные data URI работают одинаково на эндпоинтах изображений и видео, в тех же пределах и с теми же проверками при приёме.
Повтор создаёт новую задачу и не трогает старую
POST /api/v1/jobs/retry создаёт новую задачу из неудавшейся или истёкшей и заново проверяет схему, цену, права и доступность. Исходная запись остаётся нетронутой.
Один автомат состояний на всю интеграцию
queued, running, succeeded, failed, expired. Эти пять слов описывают любой медиаэндпоинт, поэтому логика переходов пишется один раз.
Перед запуском
Поведение платформы, которое стоит подтвердить
- Приведите пропорции опоры к пропорциям результата до запуска, а не в обращениях в поддержку.
- Держите опору доступной весь срок жизни задачи, а не только в момент отправки.
- Дайте повторам собственную область идемпотентности: повтор — это новая задача, а не переотправка.
- Заложите видеотарифы в обязательный дневной лимит ключа.
Частые вопросы
О чём спрашивают на этой странице
Это ваше решение и ваша юридическая ответственность. Платформа не проверяет личность на загрузках, а условия относят согласие и права к стороне клиента.
Первый кадр задаёт результат, но строгость у эндпоинтов разная. На странице каждой модели описано её поведение и доступные элементы управления.
Увеличьте duration_seconds в пределах, которые допускает эндпоинт, либо генерируйте планы по отдельности и монтируйте сами. Длительность ограничена по эндпоинтам и тарифицируется посекундно.
Вы получите конечную запись со стабильным errorCode, резерв освободится полностью, а повтор создаст новую задачу из того же исходника, не трогая старую запись.
Модели
Модели, которые можно вызвать для этой задачи
Каждая ссылка ведёт на страницу семейства моделей: входные данные, ограничения, контентная политика и текущая цена за единицу.
AlibabaWan 3.0Изображение в видеоПолитика контента: Без цензурыByteDanceSeedance 2.5Видео по референсуПолитика контента: Без цензурыKlingKling 3.0Анимация персонажаПолитика контента: С фильтромByteDanceSeedance 2.5 SpicyИзображение в видеоПолитика контента: Без цензурыAlibabaWan 3.0 PrimeВидео по референсуПолитика контента: Без цензурыKlingKling 2.6Анимация персонажаПолитика контента: С фильтром
Дальше
Попробовать эндпоинт «изображение в видео»
Превратите опорное изображение в клип. Что делают качество первого кадра, несовпадение пропорций, поля движения и длительность.