Sari la conținut
v1.1 · LiveREST · JSONUSD

Documentație API

Joburi asincrone, webhookuri semnate, endpointuri compatibile OpenAI. Plătești per rulare, iar joburile eșuate sunt rambursate.

URL de bazăhttps://api.fcaai.ai/v1

Start rapid

  1. Creează o cheieCont › Chei pentru dezvoltatori. Folosește o cheie de test ca să separi dezvoltarea de producție; rulările se facturează la fel: fcaai_test_ Pune-o în FCAAI_API_KEY; SDK-urile și CLI-ul o citesc de acolo.
  2. Instalează un SDK sau CLI-ulTypeScript pentru Node 18+, Deno, Bun și runtime-uri edge, Python 3.9+ sau terminalul. curl nu necesită instalare. npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. Rulează prima generareApelul returnează imediat 202 cu ID-ul jobului și prețul lui. Cu { wait: true }, SDK-ul returnează după ce jobul s-a terminat.
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", … }]

Autentificare

Trimite cheia ca token bearer la fiecare cerere.

  • Cheile care încep cu fcaai_live_ sunt pentru producție, iar cele care încep cu fcaai_test_ sunt pentru dezvoltare. Ambele se facturează la fel; cheile de test doar separă mediile.
  • O cheie e afișată o singură dată, când o creezi, iar noi păstrăm doar o amprentă. Păstreaz-o într-o variabilă de mediu, de exemplu FCAAI_API_KEY, niciodată în cod care rulează într-un browser sau o aplicație.
  • O cheie lipsă, greșită, revocată sau expirată returnează 401. O cheie fără permisiunea potrivită sau folosită de la un IP din afara listei de permise returnează 403.
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

Cum vin rezultatele

Fiecare generare este un job: queued → running → succeeded, failed sau canceled. Joburile eșuate și anulate sunt rambursate.

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

Anulează o generare

O generare aflată în coadă poate fi anulată, iar suma rezervată e eliberată. După ce a pornit, de obicei nu mai poate: primești 409 already_started, iar ea se termină și se taxează ca de obicei.

  • Citește mai întâi cancellable pe generare: e mereu true cât e în coadă și de obicei false după pornire.
  • Anularea unei generări deja terminate o returnează neschimbată.
# 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

Consum și sold

GET /v1/account/usage returnează generările, eșecurile și cheltuielile în USD pe zi și pe model. Acoperă ultimele 30 de zile, dacă nu transmiți from și to în formatul YYYY-MM-DD.

  • GET /v1/account/balance returnează soldul disponibil în 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"
Pas cu pas

Ghiduri

Rețete pas cu pas pentru cele mai frecvente sarcini. Exemplele folosesc SDK-urile oficiale; fila curl arată cererea HTTP simplă.

Editează o imagine cu imagini de referință

Trimite fotografia de editat și imaginile de referință într-o singură listă images, apoi descrie schimbarea. Referă-te la imagini după ordinea lor (imaginea 1, imaginea 2…).

  1. Încarcă fișiere locale sau folosește orice URL https public.
  2. Pune imaginea de editat prima în images; celelalte sunt referințe.
  3. Verifică constraints.max_input_images în detaliile modelului: arată câte imagini acceptă modelul.

Personajele, produsele și locurile salvate în bibliotecă pot fi adăugate cu element_ids (până la 3); imaginile lor de referință sunt atașate de noi.

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

Din imagine în video cu cadru de start și de final

Modelele video primesc primul cadru în image și, când îl suportă, ultimul cadru în end_image. Clipul trece de la unul la celălalt.

  1. Verifică modelul: constraints.features.end_frame trebuie să fie true, iar durata trebuie să se încadreze în constraints.duration.
  2. Trimite image, end_image, promptul și durata. Mișcările de cameră sunt text simplu în prompt.
  3. Videoclipul durează câteva minute: așteaptă cu un timeout mai lung sau folosește un webhook.

Modelele cu features.reference au și un mod de referință: trimite reference_images în loc de cadre și numește-le @Image1, @Image2 în prompt. Nu poate fi combinat cu image sau 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}}'

Fă upscale unei imagini

Upscalerele primesc o image și o scară în tier. fca/upscale are două aspecte: Standard pentru fotografii (până la 16x) și Sharp pentru randări, planuri și text (până la 4x).

  1. Află prețul pentru dimensiunea sursei: ?tier=4x&source_width=…&source_height=….
  2. Trimite imaginea și scara. "tier": "max" alege cea mai mare scară care încape (rezultat de până la 64 MP).
  3. Noua dimensiune e în width / height al rezultatului.

Îmbunătățitoarele, reiluminarea, extinderea, eliminarea fundalului și upscale-ul video sunt listate cu 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"}}}'

Rulează un șablon

Șabloanele sunt rețete gata făcute cu câteva intrări denumite. Promptul rămâne la noi: tu trimiți valori și primești înapoi o generare obișnuită.

  1. Cere șablonul ca să-i vezi inputs (cheie, tip, obligatoriu, opțiuni) și pricing.
  2. Rulează-l cu { "values": { key: value } }. Intrările de imagine primesc un URL https.
  3. Așteaptă-l ca pe orice alt job. O valoare greșită returnează 400 invalid_values cu fields.

Șabloanele în mai mulți pași (package) pornesc o rulare de șablon cu mai mulți pași: folosește 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})

Află mai întâi prețul și opțiunile modelului

Un apel gratuit returnează tot ce acceptă un model și prețul exact pentru setările tale. Folosește aceeași logică de preț ca POST /v1/generations, așa că oferta este exact ce plătești.

  1. Apelează GET /v1/models/{id} cu setările pe care le vei trimite: duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3.
  2. Citește prețul în estimate.price_usd și verifică availability înainte să rulezi.
  3. Construiește-ți formularul din options și constraints: rapoarte de aspect, rezoluții, durată, număr maxim de rezultate, număr maxim de imagini de intrare și funcții.

O valoare pe care modelul nu o permite revine în invalid_params, cu câmpul și valorile permise.

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

Încarcă-ți fișierele

Fiecare intrare e un URL https. URL-urile publice funcționează așa cum sunt; încarcă mai întâi fișierele locale și folosește url primit înapoi.

  1. Până la 50 MB: o singură cerere la POST /v1/uploads.
  2. Până la 2 GB: deschide o sesiune, trimite bucăți de 8 MB în orice ordine (și în paralel), apoi finalizeaz-o.
  3. Trimite sha256 când deschizi sesiunea ca să reiei o încărcare întreruptă sau să sari peste un fișier deja stocat.

SDK-urile și CLI-ul împart fișierul, trimit câte 3 bucăți simultan și reiau cu ID-ul sesiunii.

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

Primește rezultatele prin webhook

În loc să interoghezi, lasă-ne să-ți apelăm serverul când se termină un job. Înregistrează un URL pentru tot contul sau adaugă options.webhook_url la o singură cerere (secretul ei revine o singură dată ca webhook_secret).

  1. Înregistrează-te cu POST /v1/webhooks: URL-ul tău https și evenimentele dorite. secret e afișat o singură dată, așa că păstrează-l.
  2. Verifică fiecare livrare: X-FCAAI-Signature: t=…,v1=… este un HMAC-SHA256 al t + "." + rawBody cu secretul tău. Folosește corpul brut și respinge marcajele de timp vechi.
  3. Răspunde rapid cu 2xx și fă procesarea după aceea. O livrare eșuată se încearcă de 5 ori în total: imediat, apoi după 30 s, 2 min, 10 min și 1 h. Fiecare încercare apare în GET /v1/webhooks/{id}/deliveries.

Un eveniment poate sosi de mai multe ori; folosește id lui ca să sari peste duplicate.

Evenimente
generation.succeededgeneration.failedgeneration.canceledflow_run.succeededflow_run.failedflow_run.canceledtimeline.preview_readytimeline.donetimeline.failedapproval.requestedapproval.decided

Sunt acceptate doar adrese https publice, iar adresa e verificată din nou la fiecare livrare.

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"

Gestionează erorile și setările ignorate

Erorile vin ca JSON cu un error.code stabil după care poți ramifica logica. O setare care nu poate fi aplicată nu face jobul să eșueze: e listată în ignored_fields.

  1. Verifică statusul HTTP și error.code. Când o valoare e greșită, allowed listează valorile valide.
  2. Reîncearcă 429 și 5xx după Retry-After, cu același Idempotency-Key, ca nimic să nu fie taxat de două ori. SDK-urile le fac pe amândouă pentru tine.
  3. Citește ignored_fields în răspunsul 202; fiecare intrare are field · reason · message.

Joburile eșuate sunt rambursate automat. Dacă ruta obișnuită a unui model e căzută, jobul trece singur pe o rută de rezervă; 503 model_unavailable înseamnă că nicio rută nu e liberă acum.

StareCoduriCe faci
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowedUn câmp lipsește sau nu e permis pentru acest model. Corectează cererea; dacă o trimiți din nou neschimbată, eșuează din nou.
401invalid_api_keyapi_key_revokedapi_key_expiredCheia lipsește, e greșită, revocată sau expirată.
402insufficient_balancekey_spend_cap_reachedSold insuficient sau cheia și-a atins plafonul lunar. Nu s-a perceput nimic.
403insufficient_scopeip_not_allowedCheii îi lipsește o permisiune (vezi required_scope) sau IP-ul cererii nu e în lista ei de permise.
404model_not_foundNu există un astfel de model sau nu este deschis cheii tale.
429rate_limitedPrea multe cereri. Așteaptă timpul din Retry-After.
503model_unavailableModelul e ocupat sau offline. Reîncearcă în scurt timp sau alege alt model.
Motive în ignored_fields
unknown_field
Nu e un câmp al acestei cereri; verifică ortografia.
not_supported_by_model
Un câmp valid pe care acest model nu îl acceptă.
nearest_supported
Raportul de aspect nu e oferit; se folosește cel mai apropiat.
follows_input_image
La editare, acest model păstrează dimensiunea sau raportul imaginii de intrare.
unpriced_extra
O setare suplimentară pe care modelul nu o definește a fost eliminată.
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
}

Endpointuri compatibile OpenAI

Codul care folosește deja un client OpenAI funcționează după ce schimbi două lucruri: URL-ul de bază și cheia. Sunt acceptate chatul și generarea de imagini.

  1. Setează URL-ul de bază la https://api.fcaai.ai/v1 și folosește cheia fcaai drept cheie API.
  2. Chat: POST /v1/chat/completions cu modelul fca/chat. Streamingul, instrumentele și ieșirea JSON funcționează ca de obicei.
  3. Imagini: POST /v1/images/generations așteaptă până la 90 s și returnează data[].url. Dacă jobul durează mai mult, primești 202 cu fcaai.generation_id; urmărește-l cu GET /v1/generations/{id}.

Pentru video, audio, 3D, upscale și orice opțiune de model, folosește 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": … } }

Revinde propriilor clienți

Conturile de revânzător pot deschide un subcont pentru fiecare client, îi pot da propriile chei și pot urmări consumul pe client la preț en-gros.

  1. Folosește o cheie de administrare cu permisiunea reseller:manage. Cheile clienților nu o primesc niciodată.
  2. Creează clientul cu POST /v1/reseller/subtenants, apoi cheia lui cu POST /v1/reseller/subtenants/{id}/keys. Cheia completă e afișată o singură dată.
  3. Urmărește consumul și marja pe client cu GET /v1/reseller/usage. Ca să-ți etichetezi utilizatorii finali în generări, trimite external_user_id.

Cheile fără permisiunea de revânzător primesc 403 la aceste endpointuri.

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"
Referință

Ce poți construi

69 endpointuri. Fiecare e în referința completă, cu exemple în curl, TypeScript și Python.

GET/v1/style-kitsKituri de stil
GET/v1/elementsElemente
POST/v1/video-editsEditare video: tăiere, îmbinare, imagini, text și logo, coloană sonoră (asincron, gratuit)
GET/v1/generationsListează generările
POST/v1/generationsCreează o generare (asincron)
GET/v1/generations/{id}Obține o generare (long-poll cu wait)
POST/v1/generations/{id}/cancelAnulează (soldul rezervat e eliberat)

Prețuri

Dolari per rulare, din același sold ca planul tău. Acestea sunt prețuri live la setările implicite; fiecare pagină de model listează toate prețurile după rezoluție și durată.

ModelJobAPI (USD)
Nano Banana ProImagine · imagine · 2K$0.13
GPT Image 2.5 FlareImagine · imagine · 2K$0.055
FCA Magic ProImagine · imagine · 2K$0.03
Kling 3.0 ProVideo · per secundă · 1080p$0.11
FCA Magic V3Video · per secundă · 1080p$0.017
ElevenLabs v3Audio · clip$0.024
Ofertele de preț sunt gratuiteRulările eșuate sunt rambursateReîncărcarea automată e dezactivată implicitFără plan nelimitat pe API

Chei și limite

Fiecare cheie vine cu propriile permisiuni, ritm și plafon de cheltuieli. Anteturile răspunsului arată ce a mai rămas.

120 / minRitmul implicit de cereri per cheie. X-RateLimit-*
2Joburi care rulează simultan per cheie (se poate mări).
Plafon lunarÎn USD; când e atins, cererile primesc 402 key_spend_cap_reached
PermisiuniImagine, video, audio, 3D, upscale și LLM se activează pe rând.
Listă de IP-uri permiseLeagă o cheie de adresele IP ale serverelor tale.
Idempotency-KeyReîncercarea cu aceeași cheie nu taxează niciodată de două ori.

SDK-uri și unelte

SDK-uri oficiale TypeScript și Python și un CLI. SDK-urile reîncearcă în siguranță cu chei de idempotență, așteaptă rezultatele, încarcă fișierele mari pe bucăți și verifică semnăturile webhookurilor.

TypeScriptnpmjs.com (se deschide într-o filă nouă)Node 18+, Deno, Bun și runtime-uri edge
Pythonpypi.org (se deschide într-o filă nouă)Python 3.9+, doar biblioteca standard
CLInpmjs.com (se deschide într-o filă nouă)Fiecare model din terminal
MCPConectează-ți agenții AI la aceleași modele și același sold.
Fiecare endpoint, câmp și cod de eroare

Referința interactivă: încearcă cereri în browser și copiază cod exemplu.

Referința API completă(se deschide într-o filă nouă)