API Fellowi teď umí video: klíče, modely, první požadavek

Ještě nedávno umělo API Fellowi jednu věc: text dovnitř, obrázek ven. Teď umí mnohem víc. Stejným klíčem vznikají videoklipy, vybíráte model pro obrázky i video a API Console je všechny ukazuje s cenou, takže nikdo nemusí hádat. Pokud váš produkt potřebuje obrázky nebo krátký pohyb a nechcete kvůli tomu provozovat vlastní GPU, je tento text pro vás.

Co se změnilo, stručně

• Video na stejném klíči. Image-to-video, text-to-video a klipy podle referenčních obrázků, se stejným zůstatkem a stejným tvarem požadavku jako obrázky.
• Pole model. Rychlejší a levnější model pro koncepty, silnější pro finální render. U obrázků ho můžete vynechat a dostanete přesně to, co starší integrace dostávala vždy, za stejnou cenu; požadavek na video model uvádí vždy.
• Katalog čitelný z kódu. GET /v1/api/models vrací, co smí váš klíč volat a kolik to stojí, takže si aplikace může postavit vlastní výběr modelu místo seznamu, který zastará.
• Zkratka k samotné integraci. Konzole má tlačítko „Copy for ChatGPT/Claude“, které zkopíruje celou referenci najednou. Vložte ji do svého programátorského asistenta a požádejte o klienta ve svém jazyce.

Získejte klíč

Založte si bezplatný účet, otevřete /api-console, pojmenujte klíč a vytvořte ho. Celý klíč se zobrazí přesně jednou; potom konzole drží jen náhled, takže ho hned zkopírujte do úložiště tajemství. Každý požadavek ho posílá v hlavičce bearer:

Authorization: Bearer fk_live_your_key_here

Mějte jeden klíč na prostředí nebo na produkt. Každý klíč může mít vlastní denní limit mincí - nejjednodušší způsob, jak zabránit tomu, aby chyba v testovací smyčce přes noc utratila celý zůstatek.

První obrázek

Generování je asynchronní. Zařadíte ho do fronty, hned dostanete 202 a obrázek dorazí o chvíli později:

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"
}

Hlavička Idempotency-Key je důležitější, než vypadá. Síť ztrácí odpovědi; s touto hlavičkou vrátí opakovaný pokus o stejný požadavek stejné generování místo dvojí platby. Vytvářejte ji pro každý pokus, třeba z vlastního id objednávky. Pak se dotazujte, dokud nebude hotovo, a výsledek stáhněte:

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

quality, format, aspectRatio a placené vylepšení promptu jsou volitelné a každá výchozí hodnota odpovídá tomu, co API dělalo před zavedením dané volby. Přidejte do images několik adres referenčních obrázků a požadavek poběží na modelu pro úpravy - tak zůstane postava nebo produkt rozpoznatelný napříč obrázky.

Výběr modelu

GET /v1/api/models

Vrací modely pro obrázky a video, které smí váš klíč používat, s cenami v mincích a u videa s nejdelším klipem, dostupnými rozlišeními a informací, zda je potřeba startovní snímek. Požadovaný předejte v model. Rozumný postup: levný model, dokud uživatel zkouší, a silnější pro verzi, kterou si ponechá. Aktuální čísla najdete i na stránce produktu, která je čte ze stejného kódu, který vám mince strhává.

První klip

Image-to-video začíná statickým snímkem. Nahrajte ho jednou a uložte si id:

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

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

Pak zařaďte klip do fronty stejně jako obrázek:

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
}

Dotazujte se na GET /v1/api/videos/{id}, dokud stav nebude succeeded, a stáhněte videoUrl. Klip trvá minuty, ne sekundy, takže se dotazujte v klidu a řekněte to uživatelům. Modely text-to-video nahrávání vůbec nepotřebují. Cena je za sekundu klipu ve zvoleném rozlišení; zvuk a další referenční obrázky se přičítají tam, kde je model podporuje. Klipy přes API se vždy platí mincemi; limit plánu Director platí jen pro klipy z webového video studia.

Zapojení do skutečného produktu

• Klíč držte na serveru. Nikdy ho neposílejte do prohlížeče ani mobilní aplikace. Váš backend volá nás, váš frontend volá váš backend.
• Berte to jako frontu úloh. Uložte id generování k vlastnímu záznamu, dotazujte se z workeru a uložte si vlastní kopii souboru, jakmile dorazí. Naše kopie slouží k doručení, ne jako váš archiv.
• Neúspěch je běžný výsledek. Neúspěšné generování samo vrátí mince a nahlásí jeden ze čtyř kódů: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR nebo UNKNOWN. Pro každý ukažte něco užitečného a dovolte to zkusit znovu.
• Respektujte limit požadavků na klíč. Je to ochrana proti zneužití, ne kvóta, a v konzoli ho vidíte u každého klíče. Skutečným stropem je váš zůstatek mincí.

Ceny a vracení peněz podrobněji rozebíráme v článku proč se API platí mincemi a obsah pro dospělé ve stejném API v našem průvodci API pro generování postav.

Co neumí

Webhooky zatím nejsou: dotazujete se. Bezplatná úroveň není: každé volání stojí mince, za stejnou cenu jako ve studiu. Nevykreslí to, co moderace odmítne, a obsah pro dospělé nepatří na veřejné platformy, ať je vaše aplikace jakákoli. A i když naše podmínky neomezují komerční použití toho, co vygenerujete, neslibujeme, že je obrázek jedinečný nebo prostý všech práv třetích stran - berte ho jako fotobankový snímek, který jste sami nefotili. Pokud to sedí k tomu, co stavíte, začněte v konzoli.