De Fellowi-API maakt nu video: keys, modellen, eerste request

Tot voor kort deed de Fellowi-API één ding: tekst erin, afbeelding eruit. Nu doet hij een stuk meer. Dezelfde key maakt videoclips, je kiest het model voor afbeeldingen en video, en de API Console toont ze allemaal met hun prijs, zodat niemand hoeft te gokken. Heeft je product afbeeldingen of korte beweging nodig en wil je daarvoor geen eigen GPU's draaien, dan is dit voor jou geschreven.

Wat er veranderd is, kort

• Video met dezelfde key. Image-to-video, text-to-video en clips op basis van referentiebeelden, met hetzelfde saldo en dezelfde vorm van request als afbeeldingen.
• Een veld model. Een sneller, goedkoper model voor concepten en een sterker voor de definitieve render. Bij afbeeldingen mag je het weglaten en krijg je precies wat een oudere integratie altijd kreeg, voor dezelfde prijs; een videorequest noemt altijd zijn model.
• Een catalogus die je code kan lezen. GET /v1/api/models geeft terug wat je key mag aanroepen en wat het kost, zodat je app een eigen modelkeuze kan bouwen in plaats van een lijst mee te leveren die veroudert.
• Een snelkoppeling voor de integratie zelf. De console heeft een knop „Copy for ChatGPT/Claude” die de hele referentie in één keer kopieert. Plak die in je codeerassistent en vraag om een client in jouw taal.

Een key aanmaken

Maak een gratis account, open /api-console, geef een key een naam en maak hem aan. De volledige key wordt precies één keer getoond; daarna bewaart de console alleen een voorbeeld, dus zet hem direct in je secret store. Elke request stuurt hem mee als bearer-header:

Authorization: Bearer fk_live_your_key_here

Gebruik één key per omgeving of per product. Elke key kan een eigen dagelijks coinplafond hebben, de simpelste manier om te voorkomen dat een bug in een testloop 's nachts je hele saldo opmaakt.

Je eerste afbeelding

Een generatie is asynchroon. Je plant hem in, krijgt meteen 202 terug, en de afbeelding komt iets later:

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

De header Idempotency-Key is belangrijker dan hij lijkt. Netwerken raken antwoorden kwijt; met de header levert een nieuwe poging van dezelfde request dezelfde generatie op in plaats van twee keer te betalen. Maak er één per poging, bijvoorbeeld uit je eigen order-id. Vraag daarna op tot hij klaar is en download het resultaat:

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

quality, format, aspectRatio en een betaalde promptverbetering zijn allemaal optioneel, en elke standaardwaarde is wat de API deed voor die optie bestond. Geef een paar URL's van referentiebeelden mee in images en de request draait op het bewerkingsmodel - zo blijft een personage of product herkenbaar van afbeelding tot afbeelding.

Een model kiezen

GET /v1/api/models

Dit geeft de afbeeldings- en videomodellen die je key mag gebruiken, met coinprijzen en voor video de langste clip, de beschikbare resoluties en of er een startbeeld nodig is. Geef het gewenste mee als model. Een verstandig patroon: een goedkoop model zolang een gebruiker uitprobeert, en het sterkere voor de versie die hij houdt. Actuele cijfers staan ook op de productpagina, die ze uit dezelfde code leest die je coins afschrijft.

Je eerste clip

Image-to-video begint bij een stilstaand beeld. Upload het één keer en bewaar het id:

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

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

Plan de clip daarna in, net als een afbeelding:

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
}

Vraag GET /v1/api/videos/{id} op tot de status succeeded is en download videoUrl. Een clip duurt minuten, geen seconden, dus vraag rustig op en laat je gebruikers dat weten. Text-to-video-modellen hebben helemaal geen upload nodig. De prijs is per seconde clip in de gekozen resolutie; geluid en extra referentiebeelden komen erbij waar een model ze ondersteunt. API-clips worden altijd in coins betaald; de bundel van een Director-abonnement geldt alleen voor clips uit de web-videostudio.

Inbouwen in een echt product

• Houd de key op je server. Stuur hem nooit naar een browser of mobiele app. Je backend roept ons aan, je frontend roept je backend aan.
• Behandel het als een jobqueue. Sla het generatie-id op bij je eigen record, vraag op vanuit een worker en bewaar je eigen kopie van het bestand zodra het er is. Onze kopie is voor aflevering, niet als jouw archief.
• Mislukken is een normale uitkomst. Een mislukte generatie betaalt haar coins zelf terug en meldt een van vier codes: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR of UNKNOWN. Toon voor elk iets nuttigs en laat opnieuw proberen.
• Respecteer de ratelimiet per key. Dat is een bescherming tegen misbruik, geen quotum, en je ziet hem naast elke key in de console. Het echte plafond is je coinsaldo.

Prijzen en terugbetalingen lichten we verder toe in waarom de API in coins rekent, en de volwassen content van dezelfde API in onze gids voor de API voor personagegeneratie.

Wat hij niet doet

Webhooks zijn er nog niet: je vraagt op. Een gratis niveau is er niet: elke aanroep kost coins, tegen dezelfde prijs als in de studio. Wat de moderatie afwijst, wordt niet gerenderd, en volwassen output hoort niet op publieke platforms, wat je app ook is. En hoewel onze voorwaarden commercieel gebruik van wat je genereert niet beperken, beloven we niet dat een afbeelding uniek is of vrij van alle rechten van derden. Behandel hem als stockbeeld dat je niet zelf hebt gemaakt. Past dat bij wat je bouwt, dan begin je in de console.