Přejít na obsah
v1.1 · V provozuREST · JSONUSD

Dokumentace API

Asynchronní úlohy, podepsané webhooky, endpointy kompatibilní s OpenAI. Platíš za spuštění a neúspěšné úlohy se vracejí.

Základní URLhttps://api.fcaai.ai/v1

Rychlý start

  1. Vytvořit klíčÚčet › Klíče pro vývojáře. Testovací klíč použij k oddělení vývoje od produkce; spuštění se účtují stejně: fcaai_test_ Ulož ho do FCAAI_API_KEY; SDK i CLI ho odtamtud čtou.
  2. Nainstaluj SDK nebo CLITypeScript pro Node 18+, Deno, Bun a edge runtimy, Python 3.9+, nebo terminál. curl nevyžaduje instalaci. npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. Spusť své první generováníVolání hned vrátí 202 s id úlohy a její cenou. S { wait: true } vrátí SDK odpověď, až úloha skončí.
export FCAAI_API_KEY="fcaai_test_…"

# 1) queue a job → 202 { "id", "status": "queued", "price_usd", "eta_seconds" }
curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"fca/magic-pro","input":{"prompt":"glass villa on a pine ridge at blue hour","aspect_ratio":"16:9","resolution":"2k"}}'

# 2) long poll: holds up to 60 s, returns as soon as the job ends; repeat while queued/running
curl "https://api.fcaai.ai/v1/generations/$GEN_ID?wait=50" \
  -H "Authorization: Bearer $FCAAI_API_KEY"
# → "status": "succeeded", "output": [{ "url": "https://…", "kind": "image", … }]

Ověření

Posílej svůj klíč jako bearer token s každým požadavkem.

  • Klíče začínající fcaai_live_ jsou pro produkci a klíče začínající fcaai_test_ pro vývoj. Oba se účtují stejně; testovací klíče jen oddělují prostředí.
  • Klíč se zobrazí jednou, při vytvoření, a uchováváme jen jeho otisk. Ulož ho do proměnné prostředí, třeba FCAAI_API_KEY, nikdy do kódu, který běží v prohlížeči nebo aplikaci.
  • Chybějící, chybný, zrušený nebo vypršelý klíč vrátí 401. Klíč bez správného rozsahu nebo použitý z IP mimo seznam povolených vrátí 403.
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

Jak se vracejí výsledky

Každé generování je úloha: queued → running → succeeded, failed nebo canceled. Neúspěšné a zrušené úlohy se vracejí.

{
  "id": "cmvusmtm300234pbo7l6ecl3f",
  "object": "generation",
  "model": "fca/magic-pro",
  "status": "queued",
  "price_usd": 0.03,
  "currency": "USD",
  "eta_seconds": 14,
  "output": null
}

Zrušení generování

Generování ve frontě lze zrušit a jeho rezervovaná částka se uvolní. Jakmile začne, obvykle už nejde: dostaneš 409 already_started a doběhne a účtuje se jako obvykle.

  • Nejdřív u generování přečti cancellable: ve frontě je vždy true a po startu obvykle false.
  • Zrušení už dokončeného generování ho vrátí beze změny.
# can it still be cancelled?
curl https://api.fcaai.ai/v1/generations/$GEN_ID -H "Authorization: Bearer $FCAAI_API_KEY"
# → "status": "queued", "cancellable": true, …

curl -X POST https://api.fcaai.ai/v1/generations/$GEN_ID/cancel -H "Authorization: Bearer $FCAAI_API_KEY"
# → 200: the generation, "status": "canceled"
# → 409 "already_started": it finishes and is charged as usual

Využití a zůstatek

GET /v1/account/usage vrací generování, selhání a útratu v USD po dnech a modelech. Pokrývá posledních 30 dní, pokud nepředáš from a to ve formátu RRRR-MM-DD.

  • GET /v1/account/balance vrací tvůj dostupný zůstatek v USD.
# per day and model; the last 30 days unless you pass from and to
curl "https://api.fcaai.ai/v1/account/usage?from=2026-10-01&to=2026-10-31" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/account/balance -H "Authorization: Bearer $FCAAI_API_KEY"
Krok za krokem

Návody

Recepty krok za krokem pro nejčastější úlohy. Příklady používají oficiální SDK; karta curl ukazuje čistý HTTP požadavek.

Úprava obrázku s referenčními obrázky

Pošli fotku k úpravě a své referenční obrázky v jednom seznamu images a pak popiš změnu. Na obrázky odkazuj podle pořadí (obrázek 1, obrázek 2…).

  1. Nahraj lokální soubory, nebo použij libovolnou veřejnou URL https.
  2. Obrázek k úpravě dej v images jako první; ostatní jsou reference.
  3. V podrobnostech modelu zkontroluj constraints.max_input_images: říká, kolik obrázků model přijme.

Uložené postavy, produkty a místa z knihovny přidáš přes element_ids (max. 3); jejich referenční obrázky připojíme u nás.

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-pro","input":{"prompt":"Put the armchair from image 2 next to the window. Keep the room, light and camera unchanged.","images":["https://example.com/room.jpg","https://example.com/armchair.jpg"],"resolution":"2k"}}'

# how many images this model takes
curl https://api.fcaai.ai/v1/models/google/nano-banana-pro -H "Authorization: Bearer $FCAAI_API_KEY"
# → "constraints": { "max_input_images": …, … }

Z obrázku video s počátečním a koncovým snímkem

Video modely přijímají první snímek v image a, pokud to podporují, poslední snímek v end_image. Klip přechází z jednoho do druhého.

  1. Zkontroluj model: constraints.features.end_frame musí být true a délka musí odpovídat constraints.duration.
  2. Pošli image, end_image, prompt a délku. Pohyby kamery jsou běžný text promptu.
  3. Video trvá pár minut: čekej s delším timeoutem, nebo použij webhook.

Modely s features.reference mají i režim referencí: místo snímků pošli reference_images a v promptu je pojmenuj @Image1, @Image2. Nelze ho kombinovat s image ani end_image.

# price with an end frame
curl "https://api.fcaai.ai/v1/models/kling/3.0-pro?duration=5&end_image=1" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling/3.0-pro","input":{"prompt":"slow dolly in, morning light moves across the floor","image":"https://example.com/start.jpg","end_image":"https://example.com/end.jpg","duration":5}}'

Zvětšení obrázku

Nástroje pro zvětšení přijímají jeden image a měřítko v tier. fca/upscale má dva vzhledy: Standard pro fotky (až 16x) a Sharp pro rendery, půdorysy a text (až 4x).

  1. Zjisti cenu pro velikost zdroje: ?tier=4x&source_width=…&source_height=….
  2. Pošli obrázek a měřítko. "tier": "max" vybere největší měřítko, které se pro obrázek vejde (výstup max. 64 MP).
  3. Nová velikost je ve výstupu v width / height.

Vylepšení, přesvětlení, rozšíření, odstranění pozadí a zvětšení videa vypíše GET /v1/models?type=upscale.

curl "https://api.fcaai.ai/v1/models/fca/upscale?tier=4x&source_width=1600&source_height=1000" -H "Authorization: Bearer $FCAAI_API_KEY"

curl https://api.fcaai.ai/v1/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fca/upscale","input":{"image":"https://example.com/render.jpg","tier":"4x","extra":{"look":"sharp"}}}'

Spustit šablonu

Šablony jsou hotové recepty s několika pojmenovanými vstupy. Prompt zůstává u nás: posíláš hodnoty a dostaneš zpět běžné generování.

  1. Načti šablonu a uvidíš její inputs (klíč, typ, povinnost, možnosti) a její pricing.
  2. Spusť ji s { "values": { key: value } }. Obrázkové vstupy přijímají URL https.
  3. Čekej na ni jako na jakoukoli jinou úlohu. Chybná hodnota vrátí 400 invalid_values s fields.

Vícekrokové šablony (package) spouštějí běh šablony s několika kroky: použij templates.runPackage / run_package.

curl https://api.fcaai.ai/v1/templates -H "Authorization: Bearer $FCAAI_API_KEY"
curl https://api.fcaai.ai/v1/templates/$SLUG -H "Authorization: Bearer $FCAAI_API_KEY"     # inputs, pricing, options (models[].id → run "model")

curl https://api.fcaai.ai/v1/templates/$SLUG/run \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"values":{"photo":"https://example.com/room.jpg"}}'
# → 202: a generation (poll GET /v1/generations/{id}?wait=50)
#   multi-step templates return a template_run (GET /v1/templates/runs/{id})

Nejdřív zjisti cenu a volby modelu

Jedno volání zdarma vrátí vše, co model přijímá, a přesnou cenu pro tvoje nastavení. Používá stejnou cenovou logiku jako POST /v1/generations, takže odhad je to, co zaplatíš.

  1. Zavolej GET /v1/models/{id} s nastavením, které budeš posílat: duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3.
  2. Přečti cenu v estimate.price_usd a před spuštěním zkontroluj availability.
  3. Postav formulář z options a constraints: poměry stran, rozlišení, délka, max. výstupů, max. vstupních obrázků a funkce.

Hodnota, kterou model nepovoluje, se vrátí v invalid_params, s polem a povolenými hodnotami.

curl "https://api.fcaai.ai/v1/models/google/veo-3.1?duration=8&resolution=1080p&audio=1&end_image=1" -H "Authorization: Bearer $FCAAI_API_KEY"
# → { "availability": "available",
#     "estimate": { "price_usd": …, "price_display": "$…", "currency": "USD" },
#     "options": { … }, "constraints": { … }, "input_schema": { … } }

curl "https://api.fcaai.ai/v1/models?type=video" -H "Authorization: Bearer $FCAAI_API_KEY"   # the whole catalog for your key

Nahrání souborů

Každý vstup je URL https. Veřejné URL fungují, jak jsou; lokální soubory nejdřív nahraj a použij url, kterou dostaneš zpět.

  1. Do 50 MB: jeden požadavek na POST /v1/uploads.
  2. Do 2 GB: otevři relaci, pošli části po 8 MB v libovolném pořadí (i paralelně) a pak ji dokonči.
  3. Při otevření relace pošli sha256, abys mohl navázat na přerušené nahrávání nebo přeskočit soubor, který už je uložený.

SDK i CLI soubor rozdělí, posílají 3 části najednou a navazují pomocí id relace.

# ≤ 50 MB
curl https://api.fcaai.ai/v1/uploads -H "Authorization: Bearer $FCAAI_API_KEY" -F "[email protected]"
# → 201 { "id": "…", "object": "upload", "url": "https://…", "mime": "image/jpeg", "bytes": … }

# up to 2 GB: 1) start a session
curl https://api.fcaai.ai/v1/uploads/sessions \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walkthrough.mp4","mime":"video/mp4","bytes":104857600}'
# 2) PUT each 8 MB chunk (any order, in parallel)
split -b 8388608 -d -a 4 walkthrough.mp4 part_
curl -X PUT https://api.fcaai.ai/v1/uploads/sessions/$SESSION/chunks/0 -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/octet-stream" --data-binary @part_0000
# 3) finish → { "upload": { "url": … } }
curl -X POST https://api.fcaai.ai/v1/uploads/sessions/$SESSION/complete -H "Authorization: Bearer $FCAAI_API_KEY"

Výsledky přes webhook

Místo dotazování nech nás zavolat tvůj server, až úloha skončí. Zaregistruj URL pro celý účet, nebo přidej options.webhook_url k jednomu požadavku (jeho tajný klíč se vrátí jednou jako webhook_secret).

  1. Zaregistruj přes POST /v1/webhooks: svou URL https a události, které chceš. secret se zobrazí jen jednou, tak si ho ulož.
  2. Ověř každé doručení: X-FCAAI-Signature: t=…,v1=… je HMAC-SHA256 z t + "." + rawBody s tvým tajným klíčem. Použij surové tělo a odmítej staré časové značky.
  3. Odpověz rychle 2xx a práci udělej až potom. Neúspěšné doručení se zkouší celkem 5×: hned, pak po 30 s, 2 min, 10 min a 1 h. Každý pokus je v GET /v1/webhooks/{id}/deliveries.

Událost může přijít víckrát; duplicity přeskoč podle jejího id.

Události
generation.succeededgeneration.failedgeneration.canceledflow_run.succeededflow_run.failedflow_run.canceledtimeline.preview_readytimeline.donetimeline.failedapproval.requestedapproval.decided

Přijímají se jen veřejné adresy https a adresa se kontroluje znovu při každém doručení.

curl https://api.fcaai.ai/v1/webhooks \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/fcaai-hook","events":["generation.succeeded","generation.failed"]}'
# → 201 { "id": "…", "events": [ … ], "secret": "whsec_…" }   (secret shown only here)

# or one event for one job: add to POST /v1/generations
#   "options": { "webhook_url": "https://example.com/fcaai-hook" }
# → the 202 response carries "webhook_secret" (shown only there)

# delivery log: the latest 50 attempts
curl https://api.fcaai.ai/v1/webhooks/$WEBHOOK_ID/deliveries -H "Authorization: Bearer $FCAAI_API_KEY"

Ošetření chyb a ignorovaných nastavení

Chyby se vracejí jako JSON se stabilním error.code, podle kterého můžeš větvit. Nastavení, které nelze použít, úlohu nezastaví: je uvedeno v ignored_fields.

  1. Zkontroluj HTTP stav a error.code. Když je hodnota chybná, allowed vypíše platné.
  2. 429 a 5xx opakuj po Retry-After se stejným Idempotency-Key, aby se nic neúčtovalo dvakrát. SDK obojí udělají za tebe.
  3. Přečti ignored_fields v odpovědi 202; každá položka má field · reason · message.

Neúspěšné úlohy se vracejí automaticky. Pokud obvyklá cesta modelu nefunguje, úloha se sama přesune na záložní; 503 model_unavailable znamená, že teď není volná žádná cesta.

StavKódyCo dělat
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowedPole chybí nebo není pro tento model povolené. Oprav požadavek; jeho opakované odeslání beze změny znovu selže.
401invalid_api_keyapi_key_revokedapi_key_expiredKlíč chybí, je chybný, zrušený nebo vypršel.
402insufficient_balancekey_spend_cap_reachedNedostatečný zůstatek, nebo klíč dosáhl měsíčního limitu. Nic se neúčtovalo.
403insufficient_scopeip_not_allowedKlíči chybí rozsah (viz required_scope) nebo IP požadavku není na seznamu povolených.
404model_not_foundTakový model neexistuje, nebo není pro tvůj klíč otevřený.
429rate_limitedPříliš mnoho požadavků. Počkej dobu uvedenou v Retry-After.
503model_unavailableModel je vytížený nebo offline. Zkus to za chvíli znovu nebo vyber jiný model.
Důvody v ignored_fields
unknown_field
Toto pole do tohoto požadavku nepatří; zkontroluj pravopis.
not_supported_by_model
Platné pole, které tento model nepřijímá.
nearest_supported
Poměr stran není k dispozici; použije se nejbližší.
follows_input_image
Při úpravě tento model zachovává velikost nebo poměr vstupního obrázku.
unpriced_extra
Nastavení navíc, které model nedefinuje, bylo odebráno.
import { Fcaai, FcaaiError } from '@fcaai/sdk'

type Ignored = { field: string; reason: string; message: string }
const fcaai = new Fcaai({ maxRetries: 2 }) // 429 / 5xx / network errors: retried with backoff, honoring Retry-After

try {
  const gen = await fcaai.generations.create({ model: 'google/veo-3.1', input: { prompt: 'waves at dusk, slow pan', duration: 6 } })
  const { ignored_fields = [] } = gen as unknown as { ignored_fields?: Ignored[] }
  for (const f of ignored_fields) console.warn(f.field + ' ignored (' + f.reason + '): ' + f.message)
} catch (e) {
  if (!(e instanceof FcaaiError)) throw e
  const allowed = (e.body as { error?: { allowed?: unknown[] } } | null)?.error?.allowed
  if (e.status === 400) console.error(e.code, e.message, allowed)   // fix the request; do not retry as is
  else if (e.status === 402) console.error('Top up, or raise the key cap:', e.message)
  else if (e.code === 'model_unavailable') console.error('Retry shortly or pick another model')
  else throw e
}

Endpointy kompatibilní s OpenAI

Kód, který už používá klienta OpenAI, bude fungovat po změně dvou věcí: základní URL a klíče. Podporuje se chat a generování obrázků.

  1. Nastav základní URL na https://api.fcaai.ai/v1 a jako API klíč použij svůj klíč fcaai.
  2. Chat: POST /v1/chat/completions s modelem fca/chat. Streamování, nástroje i výstup JSON fungují jako obvykle.
  3. Obrázky: POST /v1/images/generations čeká až 90 s a vrátí data[].url. Pokud úloha potřebuje víc času, dostaneš 202 s fcaai.generation_id; sleduj ho přes GET /v1/generations/{id}.

Pro video, zvuk, 3D, zvětšení a všechny volby modelů použij POST /v1/generations.

curl https://api.fcaai.ai/v1/chat/completions \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fca/chat","messages":[{"role":"user","content":"Write a one-line caption for a walnut side table."}]}'

curl https://api.fcaai.ai/v1/images/generations \
  -H "Authorization: Bearer $FCAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/nano-banana-pro","prompt":"a paper plane on a wooden desk","size":"1536x1024"}'
# → { "created": …, "data": [{ "url": "https://…" }], "fcaai": { "generation_id": "…", "price_usd": … } }

Přeprodej vlastním zákazníkům

Prodejní účty mohou pro každého zákazníka založit podúčet, dát mu vlastní klíče a sledovat využití podle zákazníků za velkoobchodní cenu.

  1. Použij správcovský klíč s rozsahem reseller:manage. Zákaznické klíče ho nikdy nedostanou.
  2. Vytvoř zákazníka přes POST /v1/reseller/subtenants a pak jeho klíč přes POST /v1/reseller/subtenants/{id}/keys. Celý klíč se zobrazí jen jednou.
  3. Sleduj využití a marži podle zákazníků přes GET /v1/reseller/usage. Chceš-li u generování označit vlastní koncové uživatele, pošli external_user_id.

Klíče bez prodejního rozsahu dostanou na těchto endpointech 403.

curl https://api.fcaai.ai/v1/reseller/subtenants \
  -H "Authorization: Bearer $FCAAI_RESELLER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Acme Studio","plan":"pro","retail_markup":1.5}'

curl https://api.fcaai.ai/v1/reseller/subtenants/$CUSTOMER_ID/keys \
  -H "Authorization: Bearer $FCAAI_RESELLER_KEY" -H "Content-Type: application/json" \
  -d '{"name":"production","mode":"live"}'

curl "https://api.fcaai.ai/v1/reseller/usage?from=2026-10-01" -H "Authorization: Bearer $FCAAI_RESELLER_KEY"
Reference

Co můžeš postavit

Endpointy: 69. Každý je v úplné referenci s příklady v curl, TypeScriptu a Pythonu.

GET/v1/style-kitsStylové sady
GET/v1/elementsPrvky
POST/v1/video-editsÚprava videa: ořez, spojení, obrázky, text a logo, zvuková stopa (asynchronně, zdarma)
GET/v1/generationsSeznam generování
POST/v1/generationsVytvořit generování (asynchronně)
GET/v1/generations/{id}Načíst generování (long-poll s wait)
POST/v1/generations/{id}/cancelZrušit (rezervovaný zůstatek se uvolní)

Ceník

Dolary za spuštění, ze stejného zůstatku jako tvůj tarif. Jde o aktuální ceny při výchozím nastavení; každá stránka modelu uvádí všechny ceny podle rozlišení a délky.

ModelÚlohaAPI (USD)
Nano Banana ProObrázek · obrázek · 2K$0.13
GPT Image 2.5 FlareObrázek · obrázek · 2K$0.055
FCA Magic ProObrázek · obrázek · 2K$0.03
Kling 3.0 ProVideo · za sekundu · 1080p$0.11
FCA Magic V3Video · za sekundu · 1080p$0.017
ElevenLabs v3Audio · klip$0.024
Cenové odhady jsou zdarmaNeúspěšná spuštění se vracejíAutomatické dobíjení je ve výchozím stavu vypnutéV API není neomezený tarif

Klíče a limity

Každý klíč má vlastní rozsah, rychlost a limit útraty. Hlavičky odpovědi ukazují, kolik zbývá.

120 / minVýchozí rychlost požadavků na klíč. X-RateLimit-*
2Úlohy běžící současně na klíč (lze navýšit).
Měsíční limitV USD; po dosažení dostanou požadavky 402 key_spend_cap_reached
RozsahObrázky, video, zvuk, 3D, zvětšení a LLM se zapínají jednotlivě.
Povolené IPUzamkni klíč na IP adresy svých serverů.
Idempotency-KeyOpakování se stejným klíčem nikdy neúčtuje dvakrát.

SDK a nástroje

Oficiální SDK pro TypeScript a Python a CLI. SDK bezpečně opakují pokusy s klíči idempotence, čekají na výsledky, nahrávají velké soubory po částech a ověřují podpisy webhooků.

TypeScriptnpmjs.com (otevře se na nové kartě)Node 18+, Deno, Bun a edge runtimy
Pythonpypi.org (otevře se na nové kartě)Python 3.9+, jen standardní knihovna
CLInpmjs.com (otevře se na nové kartě)Každý model z tvého terminálu
MCPPřipoj své AI agenty ke stejným modelům a stejnému zůstatku.
Každý endpoint, pole i chybový kód

Interaktivní reference: zkoušej požadavky v prohlížeči a kopíruj ukázkový kód.

Úplná reference API(otevře se na nové kartě)