The Fellowi API Now Makes Video: Keys, Models, First Request

Until recently the Fellowi API did one thing: text in, image out. It now does rather more. The same key generates video clips, you choose the model for both images and video, and the API Console lists every one of them with its price, so nobody has to guess. If you have a product that needs pictures or short motion and you would rather not run a GPU farm to get them, this is written for you.

What changed, briefly

• Video on the same key. Image-to-video, text-to-video and reference-guided clips, with the same wallet and the same request shape as images.
• A model field. Pick a faster, cheaper model for drafts and a stronger one for the final render. For images you can leave it out and get exactly what an older integration always got, at the same price; a video request always names its model.
• A catalogue you can read from code. GET /v1/api/models returns what your key may call and what each costs, so your app can build its own picker instead of shipping a list that goes stale.
• A shortcut for the integration itself.The console has a "Copy for ChatGPT/Claude" button that copies the whole reference in one go. Paste it into your coding assistant and ask for a client in your language.

Get a key

Create a free account, open /api-console, name a key and create it. The full key is shown exactly once; after that the console only keeps a preview, so copy it into your secret store straight away. Every request carries it as a bearer header:

Authorization: Bearer fk_live_your_key_here

Keep one key per environment or per product. Each key can carry its own daily coin cap, which is the simplest way to make sure a bug in a staging loop cannot spend your whole balance overnight.

Your first image

A generation is asynchronous. You queue it, you get 202 back at once, and the picture arrives a little 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"
}

The Idempotency-Key header matters more than it looks. Networks drop responses; with the header, a retry of the same attempt returns the same generation instead of paying twice. Generate one per attempt, for example from your own order id. Then poll until it is done and download the result:

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

quality, format, aspectRatio and an optional paid prompt enhancer are all optional, and every default is what the API did before that option existed. Add up to a handful of reference image URLs in images and the request runs on the editing model instead, which is how you keep a character or a product recognisable across pictures.

Choosing a model

GET /v1/api/models

This returns the image and video models available to your key, with their coin prices and, for video, the longest clip each one makes, which resolutions it offers and whether it needs a start frame. Pass the one you want as model. A sensible pattern is a cheap model while a user is exploring and the stronger one for the version they keep. Current numbers are also on the product page, which reads them from the same code that charges you.

Your first clip

Image-to-video starts from a still. Upload it once and keep the id:

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

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

Then queue the clip, the same way as an image:

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
}

Poll GET /v1/api/videos/{id} until it succeeds and download videoUrl. A clip takes minutes rather than seconds, so poll gently and tell your users so. Text-to-video models skip the upload entirely. The price is per second of clip at the chosen resolution, with sound and extra reference stills added on top where a model supports them. API clips are always paid in coins; a Director plan allowance only covers clips made in the web video studio.

Wiring it into a real product

• Keep the key on your server. Never ship it to a browser or a mobile app. Your backend calls us; your front end calls your backend.
• Treat it as a job queue. Store the generation id with your own record, poll from a worker, and store your own copy of the file when it lands. Our copy is there for delivery, not as your archive.
• Handle failure as a normal outcome. A failed generation refunds its coins by itself and reports one of four codes: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR or UNKNOWN. Show the user something useful for each and let them try again.
• Respect the per-key rate limit. It is an abuse guard rather than a quota, and it is shown next to each key in the console. Your coin balance is the real ceiling.

We wrote up the pricing and refund logic in more depth in why the API is priced in coins, and the adult-content side of the same API in our character image API guide.

What it does not do

There are no webhooks yet: you poll. It is not a free tier: every call costs coins, at the same price as the studio. It will not render what moderation refuses, and adult output does not belong on public platforms whatever your app is. And while our terms put no restriction on commercial use of what you generate, we do not promise that a picture is unique or clear of every third-party right, so treat it the way you would treat stock imagery you did not shoot yourself. If that fits what you are building, the console is the place to start.