Hoppa till innehållet
v1.1 · LiveREST · JSONUSD

API-dokumentation

Asynkrona jobb, signerade webhooks, OpenAI-kompatibla endpoints. Du betalar per körning, och misslyckade jobb återbetalas.

Bas-URLhttps://api.fcaai.ai/v1

Snabbstart

  1. Skapa en nyckelKonto › Utvecklarnycklar. Använd en testnyckel för att hålla utveckling åtskild från produktion; körningar debiteras likadant: fcaai_test_ Lägg den i FCAAI_API_KEY; SDK:erna och CLI:t läser den därifrån.
  2. Installera en SDK eller CLI:tTypeScript för Node 18+, Deno, Bun och edge-miljöer, Python 3.9+ eller terminalen. curl behöver ingen installation. npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. Kör din första genereringAnropet returnerar 202 direkt med jobbets id och pris. Med { wait: true } returnerar SDK:n först när jobbet är klart.
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", … }]

Autentisering

Skicka din nyckel som bearer-token med varje förfrågan.

  • Nycklar som börjar med fcaai_live_ är för produktion och nycklar som börjar med fcaai_test_ är för utveckling. Båda debiteras på samma sätt; testnycklar håller bara miljöerna åtskilda.
  • En nyckel visas en gång, när du skapar den, och vi sparar bara ett fingeravtryck. Förvara den i en miljövariabel som FCAAI_API_KEY, aldrig i kod som körs i en webbläsare eller app.
  • En nyckel som saknas, är fel, har återkallats eller har gått ut returnerar 401. En nyckel utan rätt behörighet, eller som används från en IP-adress utanför dess tillåtelselista, returnerar 403.
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

Så kommer resultaten tillbaka

Varje generering är ett jobb: queued → running → succeeded, failed eller canceled. Misslyckade och avbrutna jobb återbetalas.

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

Avbryt en generering

En generering i kö kan avbrytas och dess reserverade belopp frigörs. När den har startat går det oftast inte: du får 409 already_started, och den slutförs och debiteras som vanligt.

  • Läs först cancellable på genereringen: det är alltid true medan den står i kö och oftast false när den har startat.
  • Om du avbryter en generering som redan är klar returneras den oförändrad.
# 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

Användning och saldo

GET /v1/account/usage returnerar genereringar, misslyckanden och utgifter i USD per dag och modell. Den täcker de senaste 30 dagarna om du inte skickar from och to som YYYY-MM-DD.

  • GET /v1/account/balance returnerar ditt tillgängliga saldo i 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"
Steg för steg

Guider

Steg-för-steg-recept för de vanligaste jobben. Exemplen använder de officiella SDK:erna; fliken curl visar den rena HTTP-förfrågan.

Redigera en bild med referensbilder

Skicka fotot som ska redigeras och dina referensbilder i en och samma images-lista, och beskriv sedan ändringen. Hänvisa till bilderna med deras ordning (bild 1, bild 2…).

  1. Ladda upp lokala filer, eller använd valfri offentlig https-URL.
  2. Lägg bilden som ska redigeras först i images; de andra är referenser.
  3. Kontrollera constraints.max_input_images i modellinformationen: där står hur många bilder modellen tar emot.

Sparade karaktärer, produkter och platser från ditt bibliotek kan läggas till med element_ids (upp till 3); deras referensbilder bifogas på vår sida.

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": …, … }

Bild till video med start- och slutbildruta

Videomodeller tar den första bildrutan i image och, när de stöder det, den sista bildrutan i end_image. Klippet rör sig från den ena till den andra.

  1. Kontrollera modellen: constraints.features.end_frame måste vara true och längden måste passa constraints.duration.
  2. Skicka image, end_image, prompten och längden. Kamerarörelser skrivs som vanlig text i prompten.
  3. Video tar några minuter: vänta med en längre timeout eller använd en webhook.

Modeller med features.reference har också ett referensläge: skicka reference_images i stället för bildrutor och namnge dem @Image1, @Image2 i prompten. Det kan inte kombineras med image eller 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}}'

Uppskala en bild

Uppskalare tar en image och en skala i tier. fca/upscale har två stilar: Standard för foton (upp till 16x) och Sharp för renderingar, planritningar och text (upp till 4x).

  1. Hämta priset för din källstorlek: ?tier=4x&source_width=…&source_height=….
  2. Skicka bilden och skalan. "tier": "max" väljer den största skala som passar bilden (utdata upp till 64 MP).
  3. Den nya storleken finns i utdatans width / height.

Förbättrare, omljussättning, utökning, bakgrundsborttagning och videouppskalning listas med 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"}}}'

Kör en mall

Mallar är färdiga recept med några namngivna indata. Prompten stannar hos oss: du skickar värden och får tillbaka en vanlig generering.

  1. Hämta mallen för att se dess inputs (nyckel, typ, obligatorisk, alternativ) och dess pricing.
  2. Kör den med { "values": { key: value } }. Bildindata tar en https-URL.
  3. Vänta på den som på vilket annat jobb som helst. Ett felaktigt värde returnerar 400 invalid_values med fields.

Mallar med flera steg (package) startar en mallkörning med flera steg: använd 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})

Hämta priset och modellens alternativ först

Ett gratis anrop returnerar allt en modell accepterar och exakt pris för dina inställningar. Det använder samma prislogik som POST /v1/generations, så prisuppgiften är det du betalar.

  1. Anropa GET /v1/models/{id} med de inställningar du kommer att skicka: duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3.
  2. Läs priset i estimate.price_usd och kontrollera availability innan du kör.
  3. Bygg ditt formulär utifrån options och constraints: bildformat, upplösningar, längd, max antal utdata, max antal indatabilder och funktioner.

Ett värde som modellen inte tillåter returneras i invalid_params, med fältet och de tillåtna värdena.

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

Ladda upp dina filer

Alla indata är https-URL:er. Offentliga URL:er fungerar som de är; ladda upp lokala filer först och använd den url du får tillbaka.

  1. Upp till 50 MB: en förfrågan till POST /v1/uploads.
  2. Upp till 2 GB: öppna en session, skicka delar på 8 MB i valfri ordning (även parallellt) och slutför den sedan.
  3. Skicka sha256 när du öppnar sessionen för att återuppta en avbruten uppladdning eller hoppa över en fil som redan är lagrad.

SDK:erna och CLI:t delar upp filen, skickar 3 delar åt gången och återupptar med sessions-id:t.

# ≤ 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"

Få resultat via webhook

I stället för att polla kan du låta oss anropa din server när ett jobb är klart. Registrera en URL för hela kontot, eller lägg till options.webhook_url i en enskild förfrågan (dess hemlighet returneras en gång som webhook_secret).

  1. Registrera med POST /v1/webhooks: din https-URL och de händelser du vill ha. secret visas bara en gång, så spara den.
  2. Verifiera varje leverans: X-FCAAI-Signature: t=…,v1=… är en HMAC-SHA256 av t + "." + rawBody med din hemlighet. Använd den råa bodyn och avvisa gamla tidsstämplar.
  3. Svara snabbt med 2xx och gör arbetet efteråt. En misslyckad leverans försöks totalt 5 gånger: direkt och sedan efter 30 s, 2 min, 10 min och 1 h. Varje försök finns i GET /v1/webhooks/{id}/deliveries.

En händelse kan komma fram mer än en gång; använd dess id för att hoppa över dubbletter.

Händelser
generation.succeededgeneration.failedgeneration.canceledflow_run.succeededflow_run.failedflow_run.canceledtimeline.preview_readytimeline.donetimeline.failedapproval.requestedapproval.decided

Endast offentliga https-adresser accepteras, och adressen kontrolleras på nytt vid varje leverans.

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"

Hantera fel och ignorerade inställningar

Fel returneras som JSON med en stabil error.code som du kan förgrena på. En inställning som inte kan tillämpas gör inte att jobbet misslyckas: den listas i ignored_fields.

  1. Kontrollera HTTP-statusen och error.code. När ett värde är fel listar allowed de giltiga.
  2. Försök igen vid 429 och 5xx efter Retry-After, med samma Idempotency-Key så att inget debiteras två gånger. SDK:erna gör båda åt dig.
  3. Läs ignored_fields i 202-svaret; varje post har field · reason · message.

Misslyckade jobb återbetalas automatiskt. Om en modells vanliga väg är nere flyttas jobbet automatiskt till en reservväg; 503 model_unavailable betyder att ingen väg är ledig just nu.

StatusKoderVad du ska göra
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowedEtt fält saknas eller är inte tillåtet för den här modellen. Rätta förfrågan; skickar du den igen oförändrad misslyckas den igen.
401invalid_api_keyapi_key_revokedapi_key_expiredNyckeln saknas, är fel, har återkallats eller har gått ut.
402insufficient_balancekey_spend_cap_reachedOtillräckligt saldo, eller så har nyckeln nått sitt månadstak. Inget debiterades.
403insufficient_scopeip_not_allowedNyckeln saknar en behörighet (se required_scope) eller så finns förfrågans IP-adress inte på dess tillåtelselista.
404model_not_foundIngen sådan modell, eller så är den inte öppen för din nyckel.
429rate_limitedFör många förfrågningar. Vänta den tid som anges i Retry-After.
503model_unavailableModellen är upptagen eller offline. Försök igen om en stund eller välj en annan modell.
Orsaker i ignored_fields
unknown_field
Inget fält i den här förfrågan; kontrollera stavningen.
not_supported_by_model
Ett giltigt fält som den här modellen inte tar emot.
nearest_supported
Bildformatet erbjuds inte; det närmaste används.
follows_input_image
Vid redigering behåller den här modellen indatabildens storlek eller format.
unpriced_extra
En extra inställning som modellen inte definierar togs bort.
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
}

OpenAI-kompatibla endpoints

Kod som redan använder en OpenAI-klient fungerar efter att du har ändrat två saker: bas-URL:en och nyckeln. Chatt och bildgenerering stöds.

  1. Ange https://api.fcaai.ai/v1 som bas-URL och använd din fcaai-nyckel som API-nyckel.
  2. Chatt: POST /v1/chat/completions med modellen fca/chat. Streaming, verktyg och JSON-utdata fungerar som vanligt.
  3. Bilder: POST /v1/images/generations väntar i upp till 90 s och returnerar data[].url. Om jobbet tar längre tid får du 202 med fcaai.generation_id; följ upp det med GET /v1/generations/{id}.

För video, ljud, 3D, uppskalning och alla modellalternativ använder du 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": … } }

Sälj vidare till dina egna kunder

Återförsäljarkonton kan öppna ett underkonto för varje kund, ge det egna nycklar och följa upp användningen per kund till grossistpris.

  1. Använd en administrationsnyckel med behörigheten reseller:manage. Kundnycklar får den aldrig.
  2. Skapa kunden med POST /v1/reseller/subtenants och sedan dess nyckel med POST /v1/reseller/subtenants/{id}/keys. Hela nyckeln visas bara en gång.
  3. Följ användning och marginal per kund med GET /v1/reseller/usage. Om du vill märka dina egna slutanvändare på genereringar skickar du external_user_id.

Nycklar utan återförsäljarbehörighet får 403 på dessa endpoints.

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

Vad du kan bygga

69 endpoints. Varje endpoint finns i den fullständiga referensen med exempel i curl, TypeScript och Python.

GET/v1/style-kitsStilkit
GET/v1/elementsElement
POST/v1/video-editsRedigera video: trimma, sammanfoga, bilder, text och logotyp, ljudspår (asynkront, gratis)
GET/v1/generationsLista genereringar
POST/v1/generationsSkapa en generering (asynkront)
GET/v1/generations/{id}Hämta en generering (long polling med wait)
POST/v1/generations/{id}/cancelAvbryt (reserverat saldo frigörs)

Priser

Dollar per körning, från samma saldo som din plan. Detta är aktuella priser med standardinställningar; varje modellsida listar alla priser per upplösning och längd.

ModellJobbAPI (USD)
Nano Banana ProBild · bild · 2K$0.13
GPT Image 2.5 FlareBild · bild · 2K$0.055
FCA Magic ProBild · bild · 2K$0.03
Kling 3.0 ProVideo · per sekund · 1080p$0.11
FCA Magic V3Video · per sekund · 1080p$0.017
ElevenLabs v3Ljud · klipp$0.024
Prisuppgifter är gratisMisslyckade körningar återbetalasAutomatisk påfyllning är avstängd som standardIngen obegränsad plan i API:t

Nycklar och gränser

Varje nyckel har sin egen behörighet, hastighet och sitt eget utgiftstak. Svarshuvudena visar vad som återstår.

120 / minStandardhastighet för förfrågningar per nyckel. X-RateLimit-*
2Jobb som körs samtidigt per nyckel (kan höjas).
MånadstakI USD; när taket nås får förfrågningar 402 key_spend_cap_reached
BehörighetBild, video, ljud, 3D, uppskalning och LLM aktiveras var för sig.
IP-tillåtelselistaLås en nyckel till dina servrars IP-adresser.
Idempotency-KeyEtt nytt försök med samma nyckel debiteras aldrig två gånger.

SDK:er och verktyg

Officiella SDK:er för TypeScript och Python samt ett CLI. SDK:erna gör säkra nya försök med idempotensnycklar, väntar på resultat, laddar upp stora filer i delar och verifierar webhook-signaturer.

TypeScriptnpmjs.com (öppnas i en ny flik)Node 18+, Deno, Bun och edge-miljöer
Pythonpypi.org (öppnas i en ny flik)Python 3.9+, endast standardbiblioteket
CLInpmjs.com (öppnas i en ny flik)Alla modeller från din terminal
MCPAnslut dina AI-agenter till samma modeller och samma saldo.
Alla endpoints, fält och felkoder

Den interaktiva referensen: testa förfrågningar i webbläsaren och kopiera exempelkod.

Fullständig API-referens(öppnas i en ny flik)