API Fellowi теперь делает видео: ключи, модели, первый запрос

Ещё недавно API Fellowi умел одно: текст на входе, картинка на выходе. Теперь он умеет заметно больше. Тем же ключом делаются видеоклипы, вы выбираете модель и для картинок, и для видео, а API Console показывает каждую из них с ценой, так что гадать не приходится. Если вашему продукту нужны изображения или короткое движение, а держать ради этого свою GPU-ферму не хочется, эта статья для вас.

Что изменилось, коротко

• Видео на том же ключе. Image-to-video, text-to-video и клипы по референсам, с тем же кошельком и той же формой запроса, что и у картинок.
• Поле model. Быстрая и дешёвая модель для черновиков, более сильная для финального рендера. Для картинок его можно не указывать - получите ровно то, что всегда получала старая интеграция, по той же цене; в запросе видео модель указывается всегда.
• Каталог, который читается из кода. GET /v1/api/models отдаёт то, что может вызывать ваш ключ, и сколько это стоит, так что приложение может строить собственный выбор модели, а не хранить список, который устареет.
• Короткий путь к самой интеграции. В консоли есть кнопка «Copy for ChatGPT/Claude», которая копирует весь справочник разом. Вставьте его в своего ассистента для кода и попросите клиент на вашем языке.

Получите ключ

Создайте бесплатный аккаунт, откройте /api-console, назовите ключ и создайте его. Полный ключ показывается ровно один раз, дальше консоль хранит только превью, так что сразу положите его в хранилище секретов. Каждый запрос передаёт его в заголовке:

Authorization: Bearer fk_live_your_key_here

Держите по ключу на окружение или на продукт. У каждого ключа может быть свой дневной лимит монет - это самый простой способ не дать ошибке в тестовом цикле потратить весь баланс за ночь.

Первая картинка

Генерация асинхронная. Вы ставите её в очередь, сразу получаете 202, а картинка приходит чуть позже:

POST /v1/api/images
Content-Type: application/json
Authorization: Bearer fk_live_your_key_here
Idempotency-Key: 7f1c2b90-order-4411

{
  "prompt": "a ceramic mug on a linen cloth, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

Заголовок Idempotency-Key важнее, чем кажется. Сеть теряет ответы; с этим заголовком повтор той же попытки вернёт ту же генерацию, а не оплатит её дважды. Генерируйте его на каждую попытку, например из id своего заказа. Потом опрашивайте, пока не будет готово, и скачайте результат:

GET /v1/api/images/{id}          -> "queued" ... "succeeded"
GET /v1/api/images/{id}/content  -> the image bytes

quality, format, aspectRatio и платное улучшение промпта - всё необязательно, и каждое значение по умолчанию - это то, как API работал до появления этой опции. Добавьте несколько ссылок на референсы в images - и запрос пойдёт на модель редактирования: так персонаж или товар остаётся узнаваемым от картинки к картинке.

Выбор модели

GET /v1/api/models

Этот запрос возвращает модели картинок и видео, доступные вашему ключу, с ценами в монетах, а для видео - максимальную длину клипа, доступные разрешения и нужен ли стартовый кадр. Нужную передайте в model. Разумная схема - дешёвая модель, пока пользователь пробует варианты, и сильная для версии, которую он оставит. Актуальные цифры есть и на странице продукта, она берёт их из того же кода, который списывает монеты.

Первый клип

Image-to-video начинается с кадра. Загрузите его один раз и сохраните id:

POST /v1/api/uploads
{ "imageBase64": "<your start frame, base64>" }

-> { "upload": { "id": "..." } }

Затем поставьте клип в очередь так же, как картинку:

POST /v1/api/videos
Idempotency-Key: 7f1c2b90-clip-4411

{
  "model": "fellowi-image-to-video-turbo",
  "uploadId": "<id from /v1/api/uploads>",
  "prompt": "steam rises slowly from the mug, the camera drifts in",
  "durationSec": 5,
  "resolution": "720p",
  "generateAudio": false
}

Опрашивайте GET /v1/api/videos/{id}, пока статус не станет succeeded, и скачайте videoUrl. Клип делается минуты, а не секунды, так что опрашивайте без спешки и предупредите об этом пользователей. Моделям text-to-video загрузка не нужна вовсе. Цена - за секунду клипа при выбранном разрешении, звук и дополнительные референсы добавляются сверху там, где модель их поддерживает. Клипы через API всегда оплачиваются монетами; лимит плана Director действует только в веб-видеостудии.

Как встроить в настоящий продукт

• Храните ключ на сервере. Никогда не отдавайте его в браузер или мобильное приложение. Ваш бэкенд обращается к нам, ваш фронтенд - к вашему бэкенду.
• Относитесь к этому как к очереди задач. Храните id генерации рядом со своей записью, опрашивайте из воркера и сохраняйте собственную копию файла, когда он готов. Наша копия нужна для выдачи, а не как ваш архив.
• Считайте неудачу нормальным исходом. Неудачная генерация сама возвращает монеты и сообщает один из четырёх кодов: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR или UNKNOWN. Покажите пользователю понятное сообщение на каждый и дайте попробовать снова.
• Учитывайте лимит запросов на ключ. Это защита от злоупотреблений, а не квота, и она видна рядом с каждым ключом в консоли. Настоящий потолок - ваш баланс монет.

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

Чего он не делает

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