API Console

Authentication

Every request needs an API key in the Authorization header: Authorization: Bearer fk_live_.... Keys are created below and shown only once at creation - store yours somewhere safe.

Your API key

Models

Pick a model with the model field. Prices are per image, in Fellowi Coins, and are exactly what the web Image Studio charges. Text-to-image is what you get with an empty images list; sending references runs the editing model instead, which can cost a different amount.

Omit model and you get fellowi-text-to-image - the same model, and the same price, an integration written before this choice existed has always had.

curl https://fellowi.com/api/v1/api/models

Create an image

POST /v1/api/images returns 202 immediately with a queued generation; the image itself takes up to a few minutes. Send an Idempotency-Key header so a retry never pays twice.

images is optional: up to 10 public image URLs the model edits from (a companion photo, your own reference). Each one adds 10 coins to the price, and a non-empty list runs on the editing model instead of text-to-image.

curl -X POST https://fellowi.com/api/v1/api/images \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "a neon-lit cyberpunk portrait",
    "model": "fellowi-text-to-image",
    "quality": "standard",
    "format": "png",
    "aspectRatio": "1:1",
    "enhancePrompt": false,
    "enhanceStyle": "default",
    "images": []
  }'

Request options

Everything below is optional. Every default is the behaviour the API had before that option existed, so an older integration keeps working unchanged.

quality

standard or high. Sets the resolution and the price - see the table above.

format

png or jpeg. Defaults to png.

aspectRatio

auto (the default) or one of 1:1, 3:4, 4:3, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9, 9:21.

enhancePrompt / enhanceStyle

Set enhancePrompt to true to have your prompt rewritten before rendering, for 10 coins on top. enhanceStyle steers that rewrite: default, artistic, photographic, technical, anime or realistic. It is ignored when enhancePrompt is off.

images

Up to 10 publicly reachable image URLs to edit from. Sending any switches the request to the editing model. Each reference image in images adds 10 coins on top.

Poll for the result

Poll GET /v1/api/images/{id} until status is succeeded, then download imageUrl. failed generations are refunded automatically.

curl https://fellowi.com/api/v1/api/images/{id} \
  -H "Authorization: Bearer fk_live_..."

When a generation fails

A failed generation refunds its coins and reports one of four codes in failureCode: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR or UNKNOWN. Nothing more specific is published - an internal code would tell you about our pipeline rather than about your request.

Rate limits and cost

Each key has its own requests-per-minute limit (visible in the panel below), and can carry a daily coin cap. These are abuse guards, not the real ceiling - your Fellowi Coins balance is what actually limits how many images you can generate. 403 with an HTML page: the request was stopped before it reached the API, usually because of its User-Agent. The default Python-urllib one is blocked, so send your own, for example User-Agent: my-app/1.0.