API 說明文件
非同步工作、簽章 Webhook、OpenAI 相容端點。按次付費,失敗的工作會退款。
https://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。失敗與取消的工作都會退款。
- 長輪詢:
?wait=50會讓請求保持開啟最多 60 秒,工作一結束就立即回傳。 - Webhook:工作結束時傳送一個簽章事件。
- SDK:TypeScript 用
{ wait: true },Python 用wait=True。
{
"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 略過重複的事件。
只接受公開的 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 表示目前沒有可用的路線。
| 狀態 | 代碼 | 處理方式 |
|---|---|---|
| 400 | invalid_bodyinvalid_durationinvalid_aspect_ratiomodel_not_allowed | 缺少欄位,或此模型不允許該欄位。請修正請求;原封不動再次送出仍會失敗。 |
| 401 | invalid_api_keyapi_key_revokedapi_key_expired | 金鑰未提供、錯誤、已撤銷或已過期。 |
| 402 | insufficient_balancekey_spend_cap_reached | 餘額不足,或金鑰已達每月上限。沒有收取任何費用。 |
| 403 | insufficient_scopeip_not_allowed | 金鑰缺少權限範圍(見 required_scope),或請求的 IP 不在其允許清單中。 |
| 404 | model_not_found | 沒有這個模型,或你的金鑰無法使用它。 |
| 429 | rate_limited | 請求過多。請等待 Retry-After 指定的時間。 |
| 503 | model_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 範例。
/v1/models列出模型/v1/models/{id}模型詳細資訊 + 價格估算/v1/voices你的複製聲音/v1/style-kits風格套件/v1/elements元素/v1/voice-styles說話風格/v1/voices/clone複製聲音(需取得同意)/v1/voices/{id}重新命名複製聲音/v1/voices/{id}刪除複製聲音(永久)/v1/models/{id}/voices語音模型可用的聲音/v1/templates列出範本/v1/templates/{slug}取得範本及其輸入/v1/templates/{slug}/run執行範本(非同步)/v1/templates/runs/{id}取得多步驟範本執行/v1/templates/runs/{id}/plan核准或改寫範本執行計畫/v1/templates/runs/{id}/cancel取消多步驟範本執行/v1/flows列出流程/v1/flows/{id}取得流程及其輸入/v1/flows/{id}/run執行流程(非同步)/v1/community/templates列出社群範本/v1/community/templates/{id}取得社群範本/v1/flows/runs/{id}取得流程執行/v1/timelines建立場景時間軸/v1/timelines/{id}取得時間軸/v1/timelines/{id}/{action}預覽、核准、轉為完整品質、剪輯/v1/farm/jobs列出渲染農場工作/v1/farm/jobs/{id}/pause暫停渲染農場工作/v1/farm/jobs/{id}/resume繼續渲染農場工作/v1/farm/jobs/{id}取得渲染農場工作/v1/video-edits編輯影片:修剪、合併、圖片、文字與標誌、配樂(非同步,免費)/v1/generations列出生成/v1/generations建立生成(非同步)/v1/generations/{id}取得生成(以 wait 長輪詢)/v1/generations/{id}/cancel取消(釋出預留餘額)/v1/uploads上傳輸入檔案(≤ 50 MB)/v1/uploads/sessions開始分段上傳(最大 2 GB)/v1/uploads/sessions/{id}工作階段狀態(已接收的分段、缺少的範圍)/v1/uploads/sessions/{id}取消分段上傳/v1/uploads/sessions/{id}/chunks/{index}上傳一個分段(原始內文)/v1/uploads/sessions/{id}/complete完成分段上傳/v1/account帳號、金鑰與餘額/v1/account/balance餘額(USD)/v1/account/usage依日期與模型的用量/v1/webhooks列出 Webhook/v1/webhooks建立 Webhook(密鑰僅回傳一次)/v1/webhooks/{id}刪除 Webhook/v1/webhooks/{id}/deliveries傳送紀錄/v1/reseller/subtenants列出你的客戶(子租戶)/v1/reseller/subtenants建立客戶(子租戶)/v1/reseller/subtenants/{id}/keys為客戶建立 API 金鑰(密鑰僅回傳一次)/v1/reseller/usage每位客戶的用量與批發成本/v1/chat/completions對話補全(OpenAI 結構描述)/v1/images/generations圖片生成(OpenAI 結構描述,同步 ≤ 90 秒)/v1/boards/{board_id}/approvals列出畫板上的核准請求/v1/boards/{board_id}/approvals/{request_id}取得核准請求/v1/boards/{board_id}/approvals/{request_id}/decide核准某個選項或要求修改/v1/plans/read判讀平面圖/v1/panoramas/finish完成 360° 環景/v1/flows/runs/{id}/cancel取消流程執行/v1/architecture/projects列出 Architecture Studio 專案/v1/architecture/projects建立專案/v1/architecture/projects/{id}取得專案及其項目/v1/architecture/projects/{id}/items加入專案/v1/architecture/projects/{id}/compliance列出「示意圖」標籤/v1/architecture/projects/{id}/compliance新增「示意圖」標籤/v1/architecture/projects/{id}/compliance/{stamp}撤回標籤/v1/architecture/projects/{id}/products圖片的產品清單/v1/architecture/projects/{id}/products從渲染圖製作產品清單/v1/architecture/products/{id}取得或下載產品清單價格
每次執行以美元計價,與你的方案共用同一個餘額。以下為預設設定下的即時價格;每個模型頁面都會依解析度與長度列出所有價格。
| 模型 | 工作 | 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 |
金鑰與限制
每組金鑰都有自己的權限範圍、速率與支出上限。回應標頭會顯示剩餘額度。
X-RateLimit-*key_spend_cap_reachedSDK 與工具
官方 TypeScript 與 Python SDK,以及 CLI。SDK 會以冪等鍵安全地重試、等待結果、分段上傳大型檔案,並驗證 Webhook 簽章。
互動式參考資料:在瀏覽器中試用請求並複製範例程式碼。
