Skip to main content
POST
Image-to-video: submit a video generation task from a reference image
Интерактивная Playground справа поддерживает отладку в реальном времени. Укажите ваш API-ключ в поле Authorization (формат: Bearer sk-xxx), загрузите опорное изображение, введите prompt, выберите model / size / seconds и отправьте.
Область применения: На этой странице описано «генерирование видео по опорному изображению» — загрузите одно изображение как стартовый кадр / визуальную опору, чтобы анимировать статичные визуальные материалы. Если опорное изображение не требуется, используйте эндпоинт Text-to-Video (тот же путь, тело JSON).
⚠️ Размеры опорного изображения должны точно совпадать с size
  • Размеры загруженного изображения в пикселях должны точно совпадать со значением поля size (например, для size=1280x720 требуется изображение 1280×720)
  • При несовпадении возвращается 400: Inpaint image must match the requested width and height
  • Перед загрузкой выполните предварительное кадрирование с помощью ffmpeg / Pillow
Дополнительные примечания:
  • Content-Type должен быть multipart/form-data (не JSON)
  • Поддерживается только один файл; имя поля фиксировано как input_reference
  • Поддерживаемые форматы: image/jpeg / image/png / image/webp

Примеры кода

Python (OpenAI SDK, совместимый без изменений)

Python (сырые запросы + multipart)

cURL

Node.js (fetch + FormData)

JavaScript в браузере

Краткая справка по параметрам

Подробные ограничения параметров, допустимые значения и примеры доступны в правой части Playground. input_reference необходимо загружать через multipart — URL и base64 не принимаются.

Подготовка референсного изображения

1

Выберите целевое разрешение

Сначала выберите size в зависимости от сценария использования: портрет 720x1280, альбомная ориентация 1280x720, альбомная ориентация Pro 1080p 1920x1080 и т. д.
2

Обрежьте локально до точного числа пикселей

Используйте Pillow / ffmpeg, чтобы обрезать изображение до целевых размеров:
Или однострочный ffmpeg:
3

Выберите подходящий формат

Предпочитайте PNG (без потерь, идеально для иллюстраций / скриншотов), JPEG для фотографий, чтобы экономить байты, WebP, если нужна прозрачность.
4

Focus the prompt on "motion" not "appearance"

Референсное изображение уже задает визуальную часть. Промпт должен быть сосредоточен на том, как это должно анимироваться: движение камеры вперед/назад, движение объектов, изменения освещения, выражения лица персонажей и т. д. Пример: "Camera slowly pushes in, leaves gently swaying, sunlight flickering through branches".

Формат ответа

Формат ответа идентичен Text-to-Video: при отправке возвращаются id + status: "queued", при опросе отображается прогресс, а по завершении загрузка выполняется через /v1/videos/{id}/content в формате MP4.
⚠️ Распространенные ошибки 400
  • Inpaint image must match the requested width and height — размеры опорного изображения не совпадают с size. Самая распространенная. Проверьте размеры на стороне клиента перед загрузкой
  • Invalid file format — загруженный файл не jpeg / png / webp или поврежден
  • Missing required parameter: input_reference — неверное имя поля multipart (должно быть input_reference, а не image или reference)
  • seconds must be one of "4", "8", "12" — передано целое число 4 вместо строки "4"
Image-to-video и text-to-video имеют одинаковую тарификацию по секундам (оплата списывается по seconds); загрузка опорного изображения не требует доплаты. См. таблицу тарификации.

Авторизации

Authorization
string
header
обязательно

API Key from the APIYI console (must use Sora2官转 group + usage-based billing)

Тело

multipart/form-data
model
enum<string>
по умолчанию:sora-2
обязательно

Model ID. sora-2 supports 720p only; sora-2-pro supports 720p / 1024p / 1080p

Доступные опции:
sora-2,
sora-2-pro
prompt
string
обязательно

Video generation prompt. Focus on how the image should animate: camera motion, object motion, lighting changes

Пример:

"Animate this scene: gentle waves lapping, leaves swaying, cinematic camera push-in"

input_reference
file
обязательно

Reference image file used as the video's starting frame / visual anchor.

  • Accepted formats: image/jpeg / image/png / image/webp
  • Dimensions must equal size, otherwise you get Inpaint image must match the requested width and height
  • Only one file is supported; field name is fixed as input_reference
seconds
enum<string>
по умолчанию:4

Video duration as string enum: "4" / "8" / "12"

Доступные опции:
4,
8,
12
size
enum<string>
по умолчанию:720x1280

Output resolution. Must exactly match the input_reference image dimensions:

  • sora-2 (720p only): 720x1280 / 1280x720
  • sora-2-pro additionally: 1024x1792 / 1792x1024 / 1080x1920 / 1920x1080
Доступные опции:
720x1280,
1280x720,
1024x1792,
1792x1024,
1080x1920,
1920x1080

Ответ

Task submitted, returns video_id with queued status

id
string

Task ID for subsequent polling and download

Пример:

"video_abc123def456"

object
string

Object type, fixed video

Пример:

"video"

model
string

Model ID used for this task

Пример:

"sora-2"

status
enum<string>

Task status:

  • queued — submitted, waiting in queue
  • in_progress — generating
  • completed — done, ready to download (/v1/videos/{id}/content)
  • failed — failed (not billed), safe to retry
Доступные опции:
queued,
in_progress,
completed,
failed
Пример:

"queued"

progress
integer

Generation progress percentage (0–100), not strictly linear

Пример:

0

created_at
integer

Task creation Unix timestamp (seconds)

Пример:

1712697600

completed_at
integer

Task completion Unix timestamp (seconds), present only on completed status

Пример:

1712697900

size
string

Actual output resolution (matches the requested size)

Пример:

"1280x720"

seconds
string

Actual duration generated (matches the requested seconds)

Пример:

"8"

quality
string

Quality tier (standard for sora-2, high for sora-2-pro)

Пример:

"standard"