Пошаговое руководство «Изображение в видео»

Подготовьте аккаунт, баланс и API-ключ

Сначала пройдите Подготовку аккаунта. В итоге у вас должны быть:

• аккаунт SpicyAPI с деньгами на балансе;
• API-ключ, который начинается с sk-spicy-;
• этот ключ, сохранённый в переменной окружения SPICY_API_KEY. Переменная окружения — это именованное значение, которое терминал передаёт запускаемым в нём программам, поэтому ключ не приходится писать ни в команде, ни в коде.

Проверьте, что ключ задан в том окне терминала, в котором вы работаете, но не выводите его целиком:

echo "${SPICY_API_KEY:0:9}"

Вы должны увидеть sk-spicy-. Если ничего не выводится или появляется ошибка, в этом окне ключ не задан; вернитесь к разделу Подготовка аккаунта.

Положите изображение в рабочую папку

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

mkdir -p ~/spicy-video
cd ~/spicy-video

Скопируйте изображение в эту папку и назовите его start-frame.jpg (или start-frame.png, если это PNG; тогда везде, где на этой странице написано start-frame.jpg, используйте это имя).

Каким должно быть исходное изображение:

• Формат и размер: JPEG, PNG, WebP или GIF, до 10 MiB (около 10 мегабайт). У модели могут быть свои, более строгие ограничения — вы увидите их на шаге 1.
• Файл действительно должен быть в этом формате. SpicyAPI проверяет содержимое файла, а не только его имя. Фотографии с телефона часто сохраняются в HEIC, и если просто переименовать такой файл в .jpg, он не станет JPEG. Сначала откройте его и экспортируйте или сохраните как JPEG.
• Форма кадра: изображение становится первым кадром. Для горизонтального видео берите широкое изображение, для вертикального — высокое; у некоторых моделей есть ещё настройка aspect_ratio.
• Права: используйте изображение, которое вам разрешено использовать.

Подготовьте выбранный инструмент

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. Выберите модель и изучите её настройки

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

spicyapi models list --modality video --task image-to-video --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

На что смотреть в списке:

Как читать настройки. inputSchema — это список настроек модели, записанный в формате JSON Schema:

• required перечисляет настройки, которые нужно отправить обязательно. У моделей этого типа среди них всегда есть image_url, а большинство требует ещё и prompt.
• properties перечисляет все настройки, которые принимает модель. У каждой есть type, description (описание простым языком, на английском) и часто enum (единственные допустимые значения), minimum и maximum, а также default (значение, которое используется, если настройку не передать).
• Внутри каждой настройки в x-ui лежат подсказки для отображения. x-ui.affects_price: true означает, что от этой настройки зависит цена.
• Некоторые модели добавляют условия на верхнем уровне, например «если отправляете A, отправьте и B». Как их читать, объясняет Контракт Spicy Schema.
• examples содержит полные входные данные, которые сервер уже проверил, — с них безопасно начинать.

Настройки, которые встречаются чаще всего. Имена одинаковы у всех моделей, но каждая модель принимает только часть из них, и у каждой свои допустимые значения:

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

2. Загрузите изображение

Что сделать: загрузите start-frame.jpg и скопируйте полученный адрес spicy://. Загрузка бесплатна.

spicyapi files upload start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z

Что произошло: изображение сохранено в закрытом виде, только для вашего аккаунта, проверено (его настоящий формат должен совпадать с заявленным типом) и получило адрес spicy://. Это не веб-ссылка: пользоваться адресом может только ваш аккаунт и только во входных данных задачи. Адрес действует один день (см. expiresAt); после этого загрузите изображение заново.

Если загрузка не удалась:

3. Опишите видео и проверьте цену

Что сделать: запишите настройки в файл input.json и запросите расчёт стоимости.

Запишите input.json. Начните с двух настроек, которые принимает любая модель для генерации видео из изображения. В prompt напишите свою фразу, а значение image_url замените на uri, скопированный на шаге 2:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

Для настроек, которые вы не передали, используется значение default модели. Чтобы задать их самостоятельно, добавляйте только настройки из properties вашей модели и только с допустимыми значениями. Например, если у вашей модели есть duration_seconds и resolution и она допускает такие значения:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Сохраните файл в рабочей папке:

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Кавычки должны быть обычными прямыми ("), а не типографскими, и после последней настройки не должно быть запятой.

Получите расчёт стоимости:

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: …
maxCharge: …
currency: USD
quantity: 5
unit: per_second
expiresAt: 2026-09-17T08:05:00Z

Что произошло: SpicyAPI сверил входные данные с настройками модели и рассчитал стоимость именно этого запроса. Ничего не запущено и ничего не списано. estimatedCost — ориентировочная стоимость, то есть сумма, которая будет зарезервирована, если запустить генерацию сейчас, а maxCharge — максимальная сумма списания. quantity и unit показывают, за что вы платите, например за 5 секунд.

Расчёт стоимости действует пять минут и только для этих входных данных. Чтобы сравнить цены, измените длительность или разрешение и рассчитайте стоимость снова. При расчёте выполняются те же проверки, что и при запуске задачи, поэтому проблемы бесплатно обнаруживаются уже здесь: 400 означает, что входные данные не соответствуют настройкам модели (исправьте input.json, сверившись с шагом 1), а 40201 — что баланса не хватит. Остальные коды перечислены на шаге 7.

4. Запустите генерацию

Ключ идемпотентности простыми словами. Это метка для одного видео, что-то вроде номера заказа. Если соединение оборвалось и вы не уверены, запустилось ли видео, отправьте тот же запрос ещё раз с той же меткой: SpicyAPI вернёт уже запущенную задачу, а не запустит вторую и не возьмёт за неё деньги. Метка действует 24 часа с тем же API-ключом. Для другого видео нужна новая метка: та же метка с другими входными данными отклоняется с кодом 409. Подробнее — в разделе Идемпотентность.

Что сделать:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json

Estimated charge: USD …; maximum charge: USD …. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? … Continue? [y/N]

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

Что произошло: SpicyAPI принял генерацию — теперь это задача — и зарезервировал estimatedCost на вашем балансе. Больше этой суммы видео стоить не может. state: queued означает, что задача ждёт своей очереди. deadlineAt — самый поздний момент, к которому она может завершиться; если к этому времени она не готова, то завершается в состоянии expired, и ничего не списывается. deadlineAt — это не срок хранения ваших файлов.

Передать расчёт стоимости — значит сказать «примите запрос, только если цена та, которую мне показали». Если за это время цена или входные данные изменились, запрос отклоняется с кодом 40901, а другая сумма не резервируется. CLI делает это за вас.

Если соединение оборвалось и вы так и не увидели ID задачи, не запускайте генерацию заново с новой меткой: так будет создано и оплачено второе видео. Повторите запрос с той же меткой:

• CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied> (вместо <the value you copied> подставьте скопированное значение Idempotency-Key). См. Как вернуться к задаче после прерванного ожидания.
• SDK: снова выполните node generate.mjs --yes; скрипт возьмёт метку из idempotency-key.txt.
• HTTP: снова выполните блок «Запуск видео»; он возьмёт метку из idempotency-key.txt.

Если шаг 4 был отклонён, ничего не создано и ничего не списано; причина и способ всё исправить — на шаге 7.

5. Дождитесь видео

Что сделать: проверяйте задачу, пока она не завершится. Видео обычно создаётся несколько минут.

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000 --json

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

Что произошло: ваш инструмент каждые несколько секунд спрашивал SpicyAPI о задаче. Состояния идут так: queued (ожидание), running (идёт генерация), затем одно конечное состояние — succeeded, failed или expired. После успеха файл копируется в собственное хранилище SpicyAPI, на это уходит ещё несколько секунд; до тех пор в результате стоит pending: true. Сумма cost окончательная, когда settled равно true.

• Закрытие терминала или Ctrl + C не отменяет задачу. Останавливается только ожидание. Сохраните ID задачи и выполните этот шаг позже.
• Не проверяйте чаще, чем раз в несколько секунд. Проверка задачи использует отдельный лимит чтения аккаунта и не расходует квоту запуска задач; см. Лимиты запросов.
• В приложении или на сервере лучше не спрашивать самим, а дать SpicyAPI сообщить о завершении задачи: см. Уведомление вместо ожидания.

6. Скачайте и сохраните видео

Что сделать: получите свежую ссылку на скачивание и сохраните файл на компьютер.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

Что произошло: к каждому результату прилагается прямая ссылка на скачивание. Она действует около 20 минут и не требует API-ключа; никогда не добавляйте к ней свой ключ. Когда срок её действия истечёт, снова запросите задачу (или воспользуйтесь files download-url), чтобы получить новую ссылку.

7. Если что-то пошло не так

Проблемы бывают двух видов, и справляются с ними по-разному.

Запрос отклонён. Команда или вызов сразу возвращает ошибку. Ничего не создано и ничего не списано. Сообщение объясняет причину, а у ошибки есть code и ID запроса (req_…), который нужно назвать, если вы обратитесь в поддержку.

Задача завершилась ошибкой. Задача была принята, но завершилась в состоянии failed или expired, а не succeeded. У задачи есть errorCode, который указывает причину, и errorMessage с более подробным описанием словами. При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.

Посмотрите их:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Затем решайте, что делать, по errorCode, а не по формулировке сообщения:

Любое другое значение обрабатывайте так же, как upstream_failed. Полный список — на странице Ошибки и повторы.

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

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait --wait-timeout-ms 1800000

Повторить можно только задачи в состоянии failed или expired. Если нужен другой вариант видео, которое создано успешно, вернитесь к шагу 3 с новой меткой. Отменить уже принятую задачу нельзя. Подробнее — в разделе Необратимость и повтор.