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 для генерації персонажів.

Чого він не робить

Вебхуків поки немає: ви опитуєте. Безкоштовного рівня немає: кожен виклик коштує монет, за тією самою ціною, що й у студії. Він не відрендерить те, що відхиляє модерація, а дорослому контенту не місце на публічних платформах, яким би не був ваш застосунок. І хоча наші умови не обмежують комерційне використання того, що ви згенерували, ми не обіцяємо, що зображення унікальне чи вільне від будь-яких прав третіх осіб, - ставтеся до нього як до стокового зображення, яке ви не знімали самі. Якщо це підходить тому, що ви будуєте, почніть із консолі.