跳至主要內容
v1.1 · 已上線REST · JSONUSD

API 說明文件

非同步工作、簽章 Webhook、OpenAI 相容端點。按次付費,失敗的工作會退款。

基礎 URLhttps://api.fcaai.ai/v1

快速開始

  1. 建立金鑰帳號 › 開發者金鑰。使用測試金鑰可以把開發與正式環境分開;兩者的執行計費方式相同: fcaai_test_ 將它放在 FCAAI_API_KEY 中;SDK 與 CLI 會從那裡讀取。
  2. 安裝 SDK 或 CLITypeScript 適用於 Node 18+、Deno、Bun 與 edge 執行環境;Python 適用於 3.9+;也可以使用終端機。curl 不需要安裝。 npm i @fcaai/sdkpip install fcaainpm i -g @fcaai/cli
  3. 執行你的第一次生成呼叫會立即回傳 202,附上工作 id 與價格。使用 { wait: true } 時,SDK 會在工作完成後才回傳。
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", … }]

驗證方式

每個請求都以 Bearer 權杖形式附上你的金鑰。

  • 以 fcaai_live_ 開頭的金鑰用於正式環境,以 fcaai_test_ 開頭的金鑰用於開發。兩者計費方式相同;測試金鑰只是用來區隔環境。
  • 金鑰只會在建立時顯示一次,我們只保留其指紋。請將它存放在環境變數中(例如 FCAAI_API_KEY),絕不要放在瀏覽器或 App 中執行的程式碼裡。
  • 未提供、錯誤、已撤銷或已過期的金鑰會回傳 401。缺少正確權限範圍的金鑰,或從允許清單以外的 IP 使用金鑰,會回傳 403。
curl https://api.fcaai.ai/v1/models \
  -H "Authorization: Bearer $FCAAI_API_KEY"

結果如何回傳

每次生成都是一個工作:queued → running → succeeded、failed 或 canceled。失敗與取消的工作都會退款。

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

取消生成

排隊中的生成可以取消,預留的金額會釋出。一旦開始執行,通常就無法取消:你會收到 409 already_started,工作會照常完成並計費。

  • 請先讀取該生成的 cancellable:排隊中時一定是 true,開始後通常是 false。
  • 取消已完成的生成時,會原樣回傳該生成。
# 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

用量與餘額

GET /v1/account/usage 會回傳依日期與模型分類的生成數、失敗數與支出(USD)。除非你以 YYYY-MM-DD 格式傳入 from 與 to,否則涵蓋最近 30 天。

  • GET /v1/account/balance 會回傳你的可用餘額(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"
逐步說明

指南

最常見工作的逐步教學。範例使用官方 SDK;curl 分頁顯示純 HTTP 請求。

用參考圖片編輯圖片

把要編輯的照片和參考圖片放在同一個 images 清單中送出,然後描述要做的修改。依順序指稱圖片(圖片 1、圖片 2…)。

  1. 上傳本機檔案,或使用任何公開的 https URL。
  2. 把要編輯的圖片放在 images 的第一個;其餘為參考圖片。
  3. 查看模型詳細資訊中的 constraints.max_input_images:它會說明模型可接受幾張圖片。

媒體庫中儲存的角色、產品與地點可以用 element_ids 加入(最多 3 個);它們的參考圖片會由我們這邊附上。

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

用起始與結束影格將圖片轉為影片

影片模型以 image 接收第一個影格;若模型支援,則以 end_image 接收最後一個影格。影片會從前者過渡到後者。

  1. 檢查模型:constraints.features.end_frame 必須為 true,且長度必須符合 constraints.duration。
  2. 送出 image、end_image、提示詞與長度。運鏡直接寫在提示詞文字中即可。
  3. 影片需要幾分鐘:請設定較長的逾時時間等待,或使用 Webhook。

具備 features.reference 的模型另有參考模式:改送 reference_images 而不是影格,並在提示詞中以 @Image1、@Image2 指稱。此模式不能與 image 或 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}}'

放大圖片畫質

放大工具接收一個 image,並以 tier 指定倍率。fca/upscale 有兩種風格:Standard 適用於照片(最高 16x),Sharp 適用於渲染圖、平面圖與文字(最高 4x)。

  1. 依你的來源尺寸取得價格:?tier=4x&source_width=…&source_height=…。
  2. 送出圖片與倍率。"tier": "max" 會選擇適合該圖片的最大倍率(輸出最高 64 MP)。
  3. 新尺寸位於輸出的 width / height 中。

強化、重新打光、擴展畫面、去背與影片放大畫質工具,都可以用 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"}}}'

執行範本

範本是附有幾個具名輸入的現成配方。提示詞保留在我們這邊:你只要送出值,就會拿回一般的生成結果。

  1. 取得範本以查看其 inputs(key、type、required、options)與 pricing。
  2. 用 { "values": { key: value } } 執行。圖片輸入需使用 https URL。
  3. 像其他工作一樣等待它完成。值錯誤時會回傳 400 invalid_values 與 fields。

多步驟範本(package)會啟動包含多個步驟的範本執行:請使用 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})

先取得價格與模型選項

一次免費呼叫就會回傳模型接受的所有內容,以及依你的設定計算的確切價格。它與 POST /v1/generations 使用相同的計價邏輯,所以報價就是你實際支付的金額。

  1. 用你要送出的設定呼叫 GET /v1/models/{id}:duration · resolution · quality · tier · count · audio=1 · images=2 · end_image=1 · reference_images=3。
  2. 執行前,從 estimate.price_usd 讀取價格並檢查 availability。
  3. 依 options 與 constraints 建立你的表單:長寬比、解析度、長度、最多輸出數、最多輸入圖片數與功能。

模型不允許的值會在 invalid_params 中回傳,並附上欄位與允許的值。

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

上傳你的檔案

每個輸入都是 https URL。公開 URL 可直接使用;本機檔案請先上傳,再使用回傳的 url。

  1. 最大 50 MB:對 POST /v1/uploads 發送一次請求。
  2. 最大 2 GB:開啟工作階段,以任意順序(也可平行)傳送 8 MB 分段,然後完成上傳。
  3. 開啟工作階段時送出 sha256,即可續傳中斷的上傳,或略過已儲存的檔案。

SDK 與 CLI 會切分檔案、一次傳送 3 個分段,並以工作階段 id 續傳。

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

透過 Webhook 取得結果

不必輪詢,讓我們在工作結束時呼叫你的伺服器。你可以為整個帳號註冊 URL,或在單一請求中加入 options.webhook_url(其密鑰會以 webhook_secret 回傳一次)。

  1. 用 POST /v1/webhooks 註冊:填入你的 https URL 與想接收的事件。secret 只會顯示一次,請妥善保管。
  2. 驗證每次傳送:X-FCAAI-Signature: t=…,v1=… 是以你的密鑰對 t + "." + rawBody 計算的 HMAC-SHA256。請使用原始內文,並拒絕過舊的時間戳記。
  3. 請盡快回應 2xx,之後再處理工作。傳送失敗時總共會嘗試 5 次:立即一次,接著在 30 秒、2 分鐘、10 分鐘與 1 小時後。每次嘗試都記錄在 GET /v1/webhooks/{id}/deliveries 中。

同一個事件可能送達不只一次;請用其 id 略過重複的事件。

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

只接受公開的 https 位址,且每次傳送時都會重新檢查位址。

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"

處理錯誤與被忽略的設定

錯誤會以 JSON 回傳,並附上穩定的 error.code,方便你據此分支處理。無法套用的設定不會讓工作失敗:它會列在 ignored_fields 中。

  1. 檢查 HTTP 狀態與 error.code。值錯誤時,allowed 會列出有效值。
  2. 遇到 429 與 5xx 時,請在 Retry-After 後以相同的 Idempotency-Key 重試,就不會重複收費。SDK 會自動幫你處理這兩件事。
  3. 讀取 202 回應中的 ignored_fields;每個項目都有 field · reason · message。

失敗的工作會自動退款。若模型平常使用的路線中斷,工作會自動改走備用路線;503 model_unavailable 表示目前沒有可用的路線。

狀態代碼處理方式
400invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowed缺少欄位,或此模型不允許該欄位。請修正請求;原封不動再次送出仍會失敗。
401invalid_api_keyapi_key_revokedapi_key_expired金鑰未提供、錯誤、已撤銷或已過期。
402insufficient_balancekey_spend_cap_reached餘額不足,或金鑰已達每月上限。沒有收取任何費用。
403insufficient_scopeip_not_allowed金鑰缺少權限範圍(見 required_scope),或請求的 IP 不在其允許清單中。
404model_not_found沒有這個模型,或你的金鑰無法使用它。
429rate_limited請求過多。請等待 Retry-After 指定的時間。
503model_unavailable模型忙碌中或離線。請稍後重試或改選其他模型。
ignored_fields 中的原因
unknown_field
不是此請求的欄位;請檢查拼字。
not_supported_by_model
有效的欄位,但此模型不接受。
nearest_supported
不提供此長寬比;將改用最接近的比例。
follows_input_image
編輯時,此模型會保留輸入圖片的尺寸或比例。
unpriced_extra
已移除模型未定義的額外設定。
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 相容端點

已經使用 OpenAI 用戶端的程式碼,只要改兩個地方就能運作:基礎 URL 與金鑰。支援對話與圖片生成。

  1. 將基礎 URL 設為 https://api.fcaai.ai/v1,並以你的 fcaai 金鑰作為 API 金鑰。
  2. 對話:POST /v1/chat/completions,模型為 fca/chat。串流、工具與 JSON 輸出都照常運作。
  3. 圖片:POST /v1/images/generations 最多等待 90 秒並回傳 data[].url。若工作需要更久,你會收到 202 與 fcaai.generation_id;請用 GET /v1/generations/{id} 追蹤。

影片、音訊、3D、放大畫質以及所有模型選項,請使用 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": … } }

轉售給你自己的客戶

經銷商帳號可以為每位客戶開立子帳號、配發專屬金鑰,並以批發價追蹤每位客戶的用量。

  1. 使用具有 reseller:manage 權限範圍的管理金鑰。客戶金鑰永遠不會取得此權限範圍。
  2. 用 POST /v1/reseller/subtenants 建立客戶,再用 POST /v1/reseller/subtenants/{id}/keys 建立其金鑰。完整金鑰只會顯示一次。
  3. 用 GET /v1/reseller/usage 追蹤每位客戶的用量與利潤。若要在生成作品上標記你自己的終端使用者,請送出 external_user_id。

沒有經銷商權限範圍的金鑰呼叫這些端點時會收到 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"
參考

你可以打造什麼

共 69 個端點。每個端點都在完整參考資料中附有 curl、TypeScript 與 Python 範例。

GET/v1/style-kits風格套件
GET/v1/elements元素
POST/v1/video-edits編輯影片:修剪、合併、圖片、文字與標誌、配樂(非同步,免費)
GET/v1/generations列出生成
POST/v1/generations建立生成(非同步)
GET/v1/generations/{id}取得生成(以 wait 長輪詢)
POST/v1/generations/{id}/cancel取消(釋出預留餘額)

價格

每次執行以美元計價,與你的方案共用同一個餘額。以下為預設設定下的即時價格;每個模型頁面都會依解析度與長度列出所有價格。

模型工作API (USD)
Nano Banana Pro圖片 · 圖片 · 2K$0.13
GPT Image 2.5 Flare圖片 · 圖片 · 2K$0.055
FCA Magic Pro圖片 · 圖片 · 2K$0.03
Kling 3.0 Pro影片 · 每秒 · 1080p$0.11
FCA Magic V3影片 · 每秒 · 1080p$0.017
ElevenLabs v3音訊 · 片段$0.024
報價免費失敗會退還點數自動儲值預設為關閉API 沒有無限方案

金鑰與限制

每組金鑰都有自己的權限範圍、速率與支出上限。回應標頭會顯示剩餘額度。

120 / 分鐘每組金鑰的預設請求速率。 X-RateLimit-*
2每組金鑰可同時執行的工作數(可提高)。
每月上限以 USD 計;達到上限時,請求會收到 402 key_spend_cap_reached
權限範圍圖片、影片、音訊、3D、放大畫質與 LLM 需逐項開啟。
IP 允許清單將金鑰鎖定在你伺服器的 IP 位址。
Idempotency-Key使用相同的冪等鍵重試,絕不會重複收費。

SDK 與工具

官方 TypeScript 與 Python SDK,以及 CLI。SDK 會以冪等鍵安全地重試、等待結果、分段上傳大型檔案,並驗證 Webhook 簽章。

TypeScriptnpmjs.com (在新分頁開啟)Node 18+、Deno、Bun 與 edge 執行環境
Pythonpypi.org (在新分頁開啟)Python 3.9+,僅使用標準函式庫
CLInpmjs.com (在新分頁開啟)在終端機使用每個模型
MCP將你的 AI 代理連接到相同的模型與相同的餘額。
所有端點、欄位與錯誤代碼

互動式參考資料:在瀏覽器中試用請求並複製範例程式碼。

完整 API 參考資料(在新分頁開啟)