我們會怎麼呼叫你的 API

先看結論：支援哪些能力

每種能力都有一套規格：要實作的端點、必要欄位、回應格式與錯誤處理。做法不符合下表任何一種的能力，目前不支援。

Embedding、語音轉文字目前不支援。

全部串接方法一覽

下表是平台目前對上游實際會打的所有方法。路徑都接在你的 Base URL（API 網址的開頭）後面。「模式」欄的意思：一次回完是同一個請求裡直接拿到結果；長任務見表格下方的說明。

長任務怎麼運作

長任務是做一次要等比較久的工作，例如生成影片。你不用把連線開著等成品，流程分成四步：

1. 1送出任務我們呼叫送出的端點，例如 POST /videos。
2. 2拿到任務編號你先回一個任務編號，不用等成品做完。
3. 3每隔幾秒查進度我們帶著編號呼叫查詢的端點，例如 GET /videos/{id}。這份文件說的「查進度」都是這一步。
4. 4完成後拿成品查到完成後，我們下載成品。

圖片、語音、圖片放大等走 POST /requests 的功能，我們送出任務後會在同一次處理內一路查進度，直到拿到成品。

連線與認證

逾時與等待

對話：POST /chat/completions

OpenAI 相容的對話服務要實作這支與 GET /models。

我們送出的欄位

其他欄位不會轉給你。你不支援的欄位，請回 400 並寫清楚原因，或忽略它並寫進你的規格，不要回 5xx。

POST {base}/chat/completions
Authorization: Bearer <API key>
Content-Type: application/json
Accept: application/json

{
  "model": "your-model-id",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 256,
  "temperature": 0.7
}

回應

其他欄位我們不使用。回應裡的 cost 我們不讀。

HTTP/1.1 200 OK
x-req-id: 7f3a9c

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "your-model-id",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hi" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 2,
    "total_tokens": 11
  }
}

請求編號（request id）

• 請在回應內容（body）放 id。沒有的話我們改讀標頭 x-request-id，再來是 request-id。
• 另外建議在所有回應（含錯誤）帶標頭 x-req-id。它和 id 分開保存，是發生錯誤時我們向你查件的依據。
• 這些值只進我們的帳與紀錄。

串流格式

串流是把回應拆成很多小塊陸續送出，下面說的「第一塊」「最後一塊」就是這些小塊。端點相同，我們多送 "stream": true 與 "stream_options": {"include_usage": true}，Accept 是 text/event-stream。

• 格式是 SSE（Server-Sent Events，伺服器持續送出文字事件的標準格式）。每個事件一行 data: <JSON>，事件之間用一個空行分隔，分隔符必須是 \n\n。用 \r\n\r\n 分隔的串流目前無法解析。
• 我們只讀 data: 開頭的行，每一行要是完整的 JSON。event: 行與註解行會略過，解析不了的行也會略過。
• 結尾送 data: [DONE]。
• usage 放在 [DONE] 之前的最後一塊，可以是 choices 為空的獨立一塊，也可以和 finish_reason 同一塊。收到多次時以最後一次為準。
• 在第一塊送出之前，請用 HTTP 狀態碼回報錯誤。
• 串流開始後，我們不解析 error 事件。連線異常中斷時，這筆記入對帳紀錄。
• 上游正常關閉卻沒有給 usage 時，我們依收到的內容長度估算（約每 4 字元 1 token）。
• 串流斷線後，我們會繼續讀到結束以取得 usage，最多再讀 120 秒，之後才中止連線。

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Hi"}}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":2,"total_tokens":11}}

data: [DONE]

模型清單：GET /models

這支是必要的，有兩個用途：

• 驗證金鑰：存入金鑰前，我們會用那把金鑰打一次，只看 HTTP 狀態。不是 2xx 就不存，連線 5 秒、回應 8 秒內要有結果。
• 更新模型清單：讀 data 陣列裡每一項的 id，另外會讀 owned_by，以及選填的 type 或 modality。

GET {base}/models

{
  "data": [
    { "id": "your-model-id", "owned_by": "your-company", "type": "text" }
  ]
}

這一步只讓我們知道你有哪些模型，不會自動上架。模型要經過我們登記價格、確認後才會開放。

錯誤碼與重試

錯誤內容請用 {"error": {"message": "…", "code": "…"}}，或 {"message": "…"}。不是 JSON 的內容會被當成一般錯誤處理。

• 我們不會對同一個上游自動重送。
• 內容審核拒絕請回 4xx，不要回 5xx，否則會被當成服務故障。
• 請不要在錯誤訊息裡放內部主機、帳號或其他敏感資訊。
• 連續失敗太多次，平台會自動暫停這個模型，見「失敗處理與自動暫停」。

usage 與計費依據

平台這邊依雙方確認的單價與下表的數量記帳，用來和你的月帳單核對。我們不讀回應裡的金額欄位。

對話的 usage 欄位

輸入與輸出分開計價時，兩個數字都要是正數。缺輸入時退回只算輸出，都缺時才依內容長度估算。usage 不準會直接影響帳，所以測試時會逐項核對。

各方法的計費數量

• 價目可以依輸入長度、解析度或時段分段。分段規則請在規格裡寫明。
• 目前不向供應商收抽成。

其他能力的規格

• 這些介面不用全做。你有提供的每項能力，只要做表上其中一種；表上只有一種就做那一種。
• 為什麼不只一種：這些都是我們的程式已經支援的格式。
• 做法不符合表上任何一種的能力，目前不支援。
• 所有上游都要實作 GET /models，並遵守「連線與認證」與「錯誤碼與重試」。

每種能力都是一套規則。下面列出必須實作的端點、必要欄位、回應格式與錯誤處理。

每項能力要做哪一種

三種影片做法的差別

共同的錯誤處理

圖片：POST /images/generations

POST /images/generations；帶輸入圖時是 POST /images/edits。結果要在同一個請求裡回完。

• 我們一律要 base64。模型支援多種格式時會送 response_format: "b64_json"；只回網址的回應會被判成異常。
• 浮水印預設關閉：模型有這個參數時，我們每次都會明確送 watermark，預設 false。
• data 是空陣列視為異常，不會以 0 張計費。

影片介面：POST /videos/generations

送出任務用 POST /videos/generations，查進度用 GET /videos/{id}，拿成品用 GET /videos/{id}/content（Accept: video/mp4，回影片檔）。

POST {base}/videos/generations
{ "model": "your-video-model", "prompt": "…", "seconds": 5,
  "resolution": "720p", "aspect_ratio": "16:9", "async": true }
→ { "id": "task_123" }

GET {base}/videos/task_123
→ { "status": "processing", "progress": 40 }
→ { "status": "completed", "usage": { … } }
→ { "status": "failed", "error": { "message": "…", "code": "…" } }

GET {base}/videos/task_123/content
→ video/mp4 bytes

影片介面：POST /videos

送出任務用 POST /videos，查進度與拿成品和 POST /videos/generations 相同。任務資料沒有 usage 時，依請求參數計算。

POST {base}/videos
{ "model": "your-video-model", "prompt": "…",
  "seconds": 5, "size": "1280x720" }
→ { "id": "task_123" }

GET {base}/videos/task_123
→ { "status": "in_progress", "progress": 40 }
→ { "status": "completed" }

通用任務介面：POST /requests

所有模型共用一組端點：POST /requests 送出任務，GET /requests/{id} 查進度。每個模型自己要用的參數放在 payload 欄位裡。這組端點可以和對話用不同網域。

POST {queue_base}/requests
{ "model": "your-model", "payload": { "prompt": "…" } }
→ { "request_id": "req_123", "status": "queued" }

GET {queue_base}/requests/req_123
→ { "status": "processing" }
→ { "status": "success",
    "outcome": { "media_urls": [{ "url": "https://…" }] } }
→ { "status": "failed", "error": { "message": "…", "code": "…" } }

payload 欄位要放什麼

輸入與成品檔案

• 輸入檔：我們給有時效的下載網址。直接放在請求裡的檔案 1 小時、已上傳素材 6 小時、音訊 15 分鐘內有效，請在這段時間內抓取。
• 成品網址：我們一完成就下載到自己的儲存，你不必長期保留，但網址至少要撐到下載完成。
• 成品網址必須是公開的 http(s) 位址，不能重新導向（3xx 視為失敗），也不能解析到私有位址。
• 單檔上限：影片 512 MB、圖片 64 MB、語音 20 MB、音樂 100 MB、3D 每檔 200 MB。

素材（選配）

有些模型要先把素材收進上游才能引用。這組端點可以有自己的 base URL 與金鑰。

失敗時回 {"isSuccess": false, "error": {"code": "…", "message": "…"}}。我們不會呼叫清單端點。

累計用量與價目（選配）

GET /dashboard/billing/usage 回 {"total_usage": <數字>}，是我們人工對帳時用的累計數字，不是必要端點。平台目前不會自動讀取上游的價目表，價格由雙方確認後人工登錄。

請求分配

請求由平台分配給上游，不保證流量。

失敗處理與自動暫停

服務連續失敗時，平台會暫停一小段時間，不把新請求送給這個模型，這就是「自動暫停」（業界常稱熔斷）。你的每個模型分開計算，只影響新請求，不影響已送出的任務。下列是目前的設定值。

• 算失敗的只有：連線失敗、逾時、5xx、429。其他 4xx、內容審核、401、403、402 都不算。
• 串流送出第一塊就算成功，之後中斷不算連續失敗。
• 暫停期間，這個模型暫時不接新請求。
• 查進度失敗不算連續失敗。5xx、429、402 會等一段時間繼續查，其他 4xx 當成最後結果，任務判失敗。
• 公開評比頁的失敗率是近 7 天「上游失敗 ÷（成功＋上游失敗）」。429 算上游失敗。

機器變動與請求量上限

如果你的容量會變動，例如閒置機器時多時少，請把請求量的限制做在你這一側。平台目前不會替對話請求控制送往上游的速度或同時請求數（併發），你回的 429 就是唯一的訊號。

• 超過容量時立刻回 429，不要把請求掛著排隊。掛著會占住連線，最後變成逾時，比 429 更糟。
• 請按模型限制，因為自動暫停也是按模型計算。
• 我們不讀 Retry-After，你可以帶，但目前沒有效果。
• 連續 429 會觸發自動暫停，並計入公開的失敗率。容量長期下降時，請通知我們調整或暫停把請求送給你。
• 規格裡請寫明每個模型最多同時處理幾個請求（併發上限）與每分鐘請求上限。這些數字是驗收與請求分配設定的依據，不是流量保證。

影片若是一件一件排隊處理，平台可以設「全平台同時處理中的件數上限」。達到上限時，新任務不會送到你這裡。

改價或下架預告

價格是我們人工登錄的，不會自動跟著你的價目變動。所以調整之前請先通知。

• 改價：請告訴我們模型、新舊價格與生效時間。
• 下架：請告訴我們模型與停止服務的時間，以及有沒有替代模型。
• 計畫性停機或容量大幅下降：請提前告訴我們，讓我們先暫停把請求送給你。
• 欄位或錯誤格式變更：也請提前通知，它會直接影響計費。
• 請在規格裡寫明你們平常用什麼方式、提前多久預告。

金鑰與帳務結構

• 平台以一個 AppleToken 帳號和金鑰呼叫你的 API。
• 用量統一計在這個帳號下，由你按月開立帳單給我們。
• 詢問與交付文件階段不需要任何金鑰。
• 進入測試後請開好這個帳號，同一帳號下測試與正式各開一把金鑰。
• 權限只開本文件列出的端點，不要給主帳號或能管理帳號的金鑰。
• 金鑰由我們加密保存，只用來呼叫你的 API。
• 交付管道另外約定，不要用一般 email 明文寄送。
• 你可以隨時撤銷這把金鑰；撤銷後呼叫會失敗，請通知我們更換。

驗收規則

下面每一項都是平台實際的行為。請先自己跑完。我們在測試環境用同一份清單實測。

所有上游

對話

串流

長任務

圖片與成品檔案

全部通過，而且雙方確認模型與價格，才會上架。只有部分能力通過時，沒通過的能力不上架。

測試上架流程

1. 1聯絡並交付資料依招商頁的八件事準備，檔案或文件網址都可以。
2. 2對照規則自我檢查逐項跑完「驗收規則」。做法不符合規格的能力目前不支援，不列入這次上架。
3. 3開帳號與測試金鑰開好 AppleToken 專用帳號與測試金鑰。金鑰存入時會打一次 GET /models，2xx 才算通過。
4. 4登記並依驗收規則實測你的服務在平台上預設是關閉的，只在測試環境打開。我們依驗收規則逐項實測。
5. 5確認模型與價格驗收全部通過後，雙方確認模型清單、單價、請求量上限與預告方式。
6. 6上架上架後名稱與評比數據公開。

這份文件描述現況，不是合約，也不是服務水準承諾。實際條件以雙方確認的內容為準。