OpenAPI 與端點索引
可下載的 OpenAPI 3.1 合約、全部公開端點與正式環境網域。
可複製的參考用戶端
下載儲存庫裡沒有任何第三方相依套件的參考程式碼。兩種實作都涵蓋模型探索、任務建立、失敗任務重試、狀態查詢、所有終態、有上限的等待、冪等鍵與錯誤處理。任務一經受理即不可取消。
這些是文件裡的範例程式，不是已發布的 npm / PyPI 套件；10 分鐘只是本機等待上限，不是正式環境的 SLA。
公開 API 的機器可讀合約是 OpenAPI 3.1 YAML。可用於產生用戶端程式碼，以及驗證整合是否符合目前公開介面。
正式環境 API 網域
https://api.spicyapi.ai 是 OpenAPI servers[0].url 宣告的正式環境 Base URL。原生任務介面位於 /api/v1，協定相容介面位於 /v1。下文分別列出，兩類用戶端的 Base URL 不能混用。
除了生成介面，平台 API 也能完成選模型、查價和消費監控。模型目錄包含帳戶價格；價格隨參數變化時，使用精確輸入報價。用量範圍固定為目前使用的 API Key。金鑰建立、輪替和預算設定在控制台完成。
模型發現、價格與帳戶 API
| 方法 | 路徑 | 用途 |
|---|---|---|
GET | /api/v1/models | 讀取目前可呼叫模型、帳號價格，以及視需要附帶的 Schema |
GET | /api/v1/models/{model} | 讀取一個模型的完整 JSON Schema |
POST | /api/v1/jobs/quote | 取得精確請求的五分鐘 USD 報價，不建立任務或凍結餘額 |
GET | /api/v1/chat/credit | 讀取可用、凍結與總餘額 |
GET | /api/v1/usage | 按日期和模型讀取目前 API Key 的呼叫與已結算費用 |
生成與任務 API
| 方法 | 路徑 | 用途 |
|---|---|---|
GET | /api/v1/jobs | 按游標分頁查詢目前 API Key 的任務歷史 |
POST | /api/v1/jobs/createTask | 建立非同步生成任務 |
GET | /api/v1/jobs/recordInfo | 查詢自己的任務 |
POST | /api/v1/jobs/retry | 從失敗或過期任務建立新任務；相容歷史 canceled 記錄 |
POST | /api/v1/jobs/stream | 呼叫文字模型，並以 SSE 串流回傳答案 |
媒體 API
| 方法 | 路徑 | 用途 |
|---|---|---|
POST | /api/v1/common/upload-url | 簽發圖片、音訊或影片直傳票據 |
POST | /api/v1/files/{fileId}/commit | 驗證並提交已直傳的檔案，回傳任務可用的 spicy:// URI |
POST | /api/v1/common/download-url | 為任務的生成結果簽發短效下載網址 |
身分驗證與回應
全部端點都認 Authorization: Bearer sk-spicy-…；相容介面（/v1、/v1beta）另外接受 Anthropic SDK 用的 x-api-key 與 Google GenAI SDK 用的 x-goog-api-key。放在網址查詢參數裡的金鑰一律不接受。原生 JSON 回應共用 {code,msg,data,request_id} 信封；任務的成敗看 data.state，不看信封的 code。/v1 與 /v1beta 回傳所選相容協定自己的物件和錯誤，SSE 也按各協定解析。
合約變更
- 不要把模型參數寫死成一份永久快照；應讀取
/models/{model}的inputSchema。 - 對未識別的回應欄位保持寬容，對未識別的請求欄位不要自行猜測。
- 上線前可把 OpenAPI YAML 交給程式碼產生器或合約測試工具。
相容介面
| 方法 | 路徑 | 協定 |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | Video status |
GET | /v1/videos/{videoId}/content | Video content |