Langkau ke kandungan
v1.1 · LangsungREST · JSONUSD

Dokumentasi API

Tugas tak segerak, webhook bertandatangan, titik akhir serasi OpenAI. Anda membayar setiap larian, dan tugas yang gagal dibayar balik.

URL asashttps://api.fcaai.ai/v1

Mula pantas

  1. Cipta kunciAkaun › Kunci pembangun. Gunakan kunci ujian untuk mengasingkan pembangunan daripada produksi; larian dibilkan dengan cara yang sama: fcaai_test_ Letakkan dalam FCAAI_API_KEY; SDK dan CLI membacanya dari situ.
  2. Pasang SDK atau CLITypeScript untuk Node 18+, Deno, Bun dan runtime edge, Python 3.9+, atau terminal. curl tidak memerlukan pemasangan. npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. Jalankan janaan pertama andaPanggilan memulangkan 202 serta-merta dengan id tugas dan harganya. Dengan { wait: true }, SDK memulangkan hasil setelah tugas selesai.
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", … }]

Pengesahan

Hantar kunci anda sebagai token bearer dengan setiap permintaan.

  • Kunci yang bermula dengan fcaai_live_ adalah untuk produksi dan kunci yang bermula dengan fcaai_test_ adalah untuk pembangunan. Kedua-duanya dibilkan dengan cara yang sama; kunci ujian hanya mengasingkan persekitaran.
  • Kunci dipaparkan sekali, semasa anda menciptanya, dan kami hanya menyimpan cap jari. Simpan dalam pemboleh ubah persekitaran seperti FCAAI_API_KEY, jangan sekali-kali dalam kod yang berjalan dalam pelayar atau aplikasi.
  • Kunci yang tiada, salah, dibatalkan atau tamat tempoh memulangkan 401. Kunci tanpa skop yang betul, atau digunakan daripada IP di luar senarai dibenarkannya, memulangkan 403.
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

Cara hasil dikembalikan

Setiap janaan ialah satu tugas: queued → running → succeeded, failed atau canceled. Tugas yang gagal dan dibatalkan dibayar balik.

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

Batalkan janaan

Janaan dalam giliran boleh dibatalkan dan jumlah yang ditempah dilepaskan. Setelah bermula, ia biasanya tidak boleh dibatalkan: anda mendapat 409 already_started, dan ia selesai serta dicaj seperti biasa.

  • Baca cancellable pada janaan dahulu: ia sentiasa true semasa dalam giliran dan biasanya false setelah bermula.
  • Membatalkan janaan yang sudah selesai memulangkannya tanpa perubahan.
# 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

Penggunaan dan baki

GET /v1/account/usage memulangkan janaan, kegagalan dan perbelanjaan dalam USD mengikut hari dan model. Ia meliputi 30 hari lepas melainkan anda menghantar from dan to sebagai YYYY-MM-DD.

  • GET /v1/account/balance memulangkan baki tersedia anda dalam 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"
Langkah demi langkah

Panduan

Resipi langkah demi langkah untuk kerja yang paling lazim. Contoh menggunakan SDK rasmi; tab curl menunjukkan permintaan HTTP biasa.

Sunting imej dengan imej rujukan

Hantar foto untuk disunting dan imej rujukan anda dalam satu senarai images, kemudian terangkan perubahannya. Rujuk imej mengikut urutannya (imej 1, imej 2…).

  1. Muat naik fail tempatan, atau gunakan mana-mana URL https awam.
  2. Letakkan imej untuk disunting dahulu dalam images; yang lain ialah rujukan.
  3. Semak constraints.max_input_images dalam butiran model: ia menyatakan bilangan imej yang diterima model.

Watak, produk dan tempat yang disimpan daripada pustaka anda boleh ditambah dengan element_ids (hingga 3); imej rujukannya dilampirkan di pihak kami.

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

Imej ke video dengan bingkai mula dan akhir

Model video menerima bingkai pertama dalam image dan, apabila disokong, bingkai terakhir dalam end_image. Klip bergerak daripada satu ke yang satu lagi.

  1. Semak model: constraints.features.end_frame mestilah true dan tempoh mesti muat dalam constraints.duration.
  2. Hantar image, end_image, prompt dan tempoh. Gerakan kamera ialah teks prompt biasa.
  3. Video mengambil masa beberapa minit: tunggu dengan had masa yang lebih panjang, atau gunakan webhook.

Model dengan features.reference juga mempunyai mod rujukan: hantar reference_images sebagai ganti bingkai dan namakan @Image1, @Image2 dalam prompt. Ia tidak boleh digabungkan dengan image atau 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}}'

Besarkan imej

Pembesar menerima satu image dan skala dalam tier. fca/upscale mempunyai dua rupa: Standard untuk foto (hingga 16x) dan Sharp untuk render, pelan dan teks (hingga 4x).

  1. Dapatkan harga untuk saiz sumber anda: ?tier=4x&source_width=…&source_height=….
  2. Hantar imej dan skala. "tier": "max" memilih skala terbesar yang muat untuk imej (output hingga 64 MP).
  3. Saiz baharu ada dalam width / height output.

Pemerhalus, pencahayaan semula, peluasan, pembuangan latar belakang dan pembesaran video disenaraikan dengan 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"}}}'

Jalankan templat

Templat ialah resipi sedia guna dengan beberapa input bernama. Prompt kekal di pihak kami: anda menghantar nilai dan menerima janaan biasa.

  1. Dapatkan templat untuk melihat inputs-nya (kunci, jenis, wajib, pilihan) dan pricing-nya.
  2. Jalankan dengan { "values": { key: value } }. Input imej menerima URL https.
  3. Tunggu seperti tugas lain. Nilai yang salah memulangkan 400 invalid_values dengan fields.

Templat berbilang langkah (package) memulakan larian templat dengan beberapa langkah: gunakan 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})

Dapatkan harga dan pilihan model dahulu

Satu panggilan percuma memulangkan semua yang diterima model dan harga tepat untuk tetapan anda. Ia menggunakan logik harga yang sama seperti POST /v1/generations, jadi sebut harga itulah yang anda bayar.

  1. Panggil GET /v1/models/{id} dengan tetapan yang akan anda hantar: duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3.
  2. Baca harga dalam estimate.price_usd dan semak availability sebelum anda jalankan.
  3. Bina borang anda daripada options dan constraints: nisbah bidang, resolusi, tempoh, output maksimum, imej input maksimum dan ciri.

Nilai yang tidak dibenarkan model dikembalikan dalam invalid_params, bersama medan dan nilai yang dibenarkan.

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

Muat naik fail anda

Setiap input ialah URL https. URL awam berfungsi seadanya; muat naik fail tempatan dahulu dan gunakan url yang anda terima.

  1. Hingga 50 MB: satu permintaan ke POST /v1/uploads.
  2. Hingga 2 GB: buka sesi, hantar ketulan 8 MB dalam sebarang urutan (juga secara selari), kemudian lengkapkannya.
  3. Hantar sha256 semasa membuka sesi untuk menyambung semula muat naik yang terganggu atau melangkau fail yang sudah disimpan.

SDK dan CLI membahagikan fail, menghantar 3 ketulan pada satu masa dan menyambung semula dengan id sesi.

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

Dapatkan hasil melalui webhook

Daripada meninjau, biarkan kami memanggil pelayan anda apabila tugas tamat. Daftarkan URL untuk keseluruhan akaun, atau tambah options.webhook_url pada satu permintaan (rahsianya dikembalikan sekali sebagai webhook_secret).

  1. Daftar dengan POST /v1/webhooks: URL https anda dan peristiwa yang anda mahu. secret dipaparkan sekali sahaja, jadi simpannya.
  2. Sahkan setiap penghantaran: X-FCAAI-Signature: t=…,v1=… ialah HMAC-SHA256 bagi t + "." + rawBody dengan rahsia anda. Gunakan badan mentah dan tolak cap masa yang lama.
  3. Jawab 2xx dengan segera dan lakukan kerja selepas itu. Penghantaran yang gagal dicuba 5 kali kesemuanya: serta-merta, kemudian selepas 30 s, 2 min, 10 min dan 1 j. Setiap percubaan ada dalam GET /v1/webhooks/{id}/deliveries.

Satu peristiwa boleh tiba lebih daripada sekali; gunakan id-nya untuk melangkau pendua.

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

Hanya alamat https awam diterima, dan alamat disemak semula pada setiap penghantaran.

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"

Kendalikan ralat dan tetapan yang diabaikan

Ralat dikembalikan sebagai JSON dengan error.code stabil yang boleh anda cabangkan. Tetapan yang tidak dapat diterapkan tidak menggagalkan tugas: ia disenaraikan dalam ignored_fields.

  1. Semak status HTTP dan error.code. Apabila nilai salah, allowed menyenaraikan yang sah.
  2. Cuba semula 429 dan 5xx selepas Retry-After, dengan Idempotency-Key yang sama supaya tiada caj berganda. SDK melakukan kedua-duanya untuk anda.
  3. Baca ignored_fields dalam respons 202; setiap entri mempunyai field · reason · message.

Tugas yang gagal dibayar balik secara automatik. Jika laluan biasa sesebuah model tergendala, tugas berpindah ke laluan sandaran dengan sendirinya; 503 model_unavailable bermakna tiada laluan yang kosong sekarang.

StatusKodApa yang perlu dilakukan
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowedSatu medan tiada atau tidak dibenarkan untuk model ini. Betulkan permintaan; menghantarnya semula tanpa perubahan akan gagal lagi.
401invalid_api_keyapi_key_revokedapi_key_expiredKunci tiada, salah, dibatalkan atau tamat tempoh.
402insufficient_balancekey_spend_cap_reachedBaki tidak mencukupi, atau kunci telah mencapai had bulanannya. Tiada caj dikenakan.
403insufficient_scopeip_not_allowedKunci tidak mempunyai skop (lihat required_scope) atau IP permintaan tiada dalam senarai dibenarkannya.
404model_not_foundTiada model sedemikian, atau ia tidak dibuka untuk kunci anda.
429rate_limitedTerlalu banyak permintaan. Tunggu selama masa dalam Retry-After.
503model_unavailableModel sedang sibuk atau luar talian. Cuba lagi sebentar lagi atau pilih model lain.
Sebab dalam ignored_fields
unknown_field
Bukan medan bagi permintaan ini; semak ejaannya.
not_supported_by_model
Medan yang sah tetapi tidak diterima model ini.
nearest_supported
Nisbah bidang itu tidak ditawarkan; yang paling hampir digunakan.
follows_input_image
Semasa menyunting, model ini mengekalkan saiz atau nisbah imej input.
unpriced_extra
Tetapan tambahan yang tidak ditakrifkan model telah dibuang.
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
}

Titik akhir serasi OpenAI

Kod yang sudah menggunakan klien OpenAI berfungsi selepas menukar dua perkara: URL asas dan kunci. Sembang dan penjanaan imej disokong.

  1. Tetapkan URL asas kepada https://api.fcaai.ai/v1 dan gunakan kunci fcaai anda sebagai kunci API.
  2. Sembang: POST /v1/chat/completions dengan model fca/chat. Penstriman, alat dan output JSON berfungsi seperti biasa.
  3. Imej: POST /v1/images/generations menunggu hingga 90 s dan memulangkan data[].url. Jika tugas memerlukan masa lebih lama, anda mendapat 202 dengan fcaai.generation_id; ikutinya dengan GET /v1/generations/{id}.

Untuk video, audio, 3D, pembesaran dan setiap pilihan model, gunakan 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": … } }

Jual semula kepada pelanggan anda sendiri

Akaun penjual semula boleh membuka subakaun bagi setiap pelanggan, memberinya kunci sendiri dan mengikuti penggunaan setiap pelanggan pada harga borong.

  1. Gunakan kunci pengurusan dengan skop reseller:manage. Kunci pelanggan tidak sekali-kali mendapatnya.
  2. Cipta pelanggan dengan POST /v1/reseller/subtenants, kemudian kuncinya dengan POST /v1/reseller/subtenants/{id}/keys. Kunci penuh dipaparkan sekali sahaja.
  3. Ikuti penggunaan dan margin setiap pelanggan dengan GET /v1/reseller/usage. Untuk menanda pengguna akhir anda sendiri pada janaan, hantar external_user_id.

Kunci tanpa skop penjual semula mendapat 403 pada titik akhir ini.

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

Apa yang boleh anda bina

69 titik akhir. Setiap satu ada dalam rujukan penuh dengan contoh curl, TypeScript dan Python.

GET/v1/style-kitsKit gaya
GET/v1/elementsElemen
POST/v1/video-editsSunting video: pangkas, cantum, imej, teks & logo, runut bunyi (tak segerak, percuma)
GET/v1/generationsSenaraikan janaan
POST/v1/generationsCipta janaan (tak segerak)
GET/v1/generations/{id}Dapatkan janaan (tinjauan panjang dengan wait)
POST/v1/generations/{id}/cancelBatal (baki yang ditempah dilepaskan)

Harga

Dolar setiap larian, daripada baki yang sama dengan pelan anda. Ini harga langsung pada tetapan lalai; setiap halaman model menyenaraikan setiap harga mengikut resolusi dan tempoh.

ModelTugasAPI (USD)
Nano Banana ProImej · imej · 2K$0.13
GPT Image 2.5 FlareImej · imej · 2K$0.055
FCA Magic ProImej · imej · 2K$0.03
Kling 3.0 ProVideo · setiap saat · 1080p$0.11
FCA Magic V3Video · setiap saat · 1080p$0.017
ElevenLabs v3Audio · klip$0.024
Sebut harga adalah percumaLarian gagal dibayar balikTambah nilai automatik dimatikan secara lalaiTiada pelan tanpa had pada API

Kunci dan had

Setiap kunci datang dengan skop, kadar dan had belanjanya sendiri. Pengepala respons menunjukkan baki yang tinggal.

120 / minKadar permintaan lalai bagi setiap kunci. X-RateLimit-*
2Tugas yang berjalan serentak bagi setiap kunci (boleh dinaikkan).
Had bulananDalam USD; apabila dicapai, permintaan mendapat 402 key_spend_cap_reached
SkopImej, video, audio, 3D, pembesaran dan LLM dihidupkan satu demi satu.
Senarai IP dibenarkanKunci sesuatu kunci kepada alamat IP pelayan anda.
Idempotency-KeyMencuba semula dengan kunci yang sama tidak sekali-kali mengecaj dua kali.

SDK dan alat

SDK TypeScript dan Python rasmi serta CLI. SDK mencuba semula dengan selamat menggunakan kunci idempotensi, menunggu hasil, memuat naik fail besar secara berketul dan mengesahkan tandatangan webhook.

TypeScriptnpmjs.com (dibuka dalam tab baharu)Node 18+, Deno, Bun dan runtime edge
Pythonpypi.org (dibuka dalam tab baharu)Python 3.9+, pustaka standard sahaja
CLInpmjs.com (dibuka dalam tab baharu)Setiap model daripada terminal anda
MCPSambungkan ejen AI anda ke model yang sama dan baki yang sama.
Setiap titik akhir, medan dan kod ralat

Rujukan interaktif: cuba permintaan dalam pelayar anda dan salin contoh kod.

Rujukan API penuh(dibuka dalam tab baharu)