驗證與基礎規範

本頁是所有介面的共用約定，包括基礎位址、驗證、請求與回應格式、分頁、限流、冪等與錯誤處理。具體介面的參數與範例請見介面總覽以及各自的介面頁面。

基礎位址

項目	值
預設基礎位址	`https://locopalai.com`
海外模型接入位址	`https://us-api.locopalai.com`（若主控台顯示其他位址，以主控台為準）
模型與生成介面	`<基礎位址>/v1/...`
素材庫介面	`<基礎位址>/api/v1/materials/...`
請求格式	`application/json`；音訊 `speech` 成功回應為二進位音訊
字元編碼	UTF-8

驗證

所有介面都使用同一把平台 API Key：

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

項目	說明
取得方式	於主控台「API 金鑰」頁面建立，可隨時啟用、停用或刪除
作用範圍	模型、文字、圖片、影片、音訊與素材介面共用同一把 Key，GET 請求同樣需要攜帶
儲存要求	只放在伺服器端環境變數或金鑰管理服務中，不要寫入瀏覽器、用戶端安裝套件或公開儲存庫

`Bearer` 前綴可以省略（但不建議）

實測四種寫法：

請求標頭	結果
`Authorization: Bearer <key>`	`200` —— 建議寫法
`Authorization: <key>`（裸 token）	`200` —— 平台同樣接受
`authorization: bearer <key>`（全小寫）	`200` —— 請求標頭名稱與驗證方案名稱不分大小寫
（完全不傳送 `Authorization`）	`401`

平台同時接受裸 token，因此傳回 200 不代表用戶端設定正確。反過來說，如果某個用戶端傳回 401，請先確認它是否漏傳了整個 Authorization 標頭，而不是直接懷疑 Key 本身。請一律使用 Bearer 寫法。

API Key 缺少、錯誤、已停用或不屬於目前帳號時，會傳回 HTTP 401：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

請注意 code 是空字串。 驗證失敗時平台不會填寫 code，所以不要用 code 是否為空來判斷 請求是否發生錯誤，應以 HTTP 狀態碼為準。message 中的 request id 可直接取出用於提出工單。

這類驗證失敗在所有介面上的結構一致，message 會帶上請求識別碼，方便排查。

回應結構

平台有三套回應結構，用戶端必須同時檢查 HTTP 狀態碼與回應內容。

模型、文字、圖片、影片與音訊介面

成功時直接傳回結果物件，失敗時傳回 HTTP 非 2xx 並附帶 error 物件：

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

影片任務查詢是例外：查不到任務時會傳回 400，回應內容為頂層 { code, message, data } 結構（code 為字串 task_not_exist），不是上述的 error 物件。詳見錯誤碼與排查。 code、type、param 的取值會隨錯誤類型變化，排查時請以 message 為主，不要只比對固定的 code 文字。

素材庫介面

成功與失敗都使用統一結構：

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

失敗時 HTTP 狀態碼與 code 一致（400 / 401 / 404 / 429 / 502 / 503）。素材審核未完成不是錯誤，而是 200 回應中的 status 欄位（Processing / Active / Failed）。

分頁

素材分組、素材清單等清單介面使用統一的分頁參數：

參數	位置	預設	上限	說明
`page`	query	`1`	—	頁碼，從 1 開始
`page_size`	query	`20`	`100`	每頁筆數，超出範圍時依預設值處理

回應中的 data.total 是總筆數，data.page、data.page_size 是本次生效的分頁參數。請一律讀取 total 判斷是否還有下一頁，不要用「本次傳回筆數」判斷。

限流與重試

情境	平台行為	建議
請求過於頻繁	HTTP `429`	退避後重試，不要並行重試
素材狀態查詢	輕量介面	每 5～10 秒輪詢一次，只輪詢同一個素材 ID
影片任務查詢	輕量介面	每 5～15 秒輪詢一次，只查詢原任務 ID
網路中斷	請求結果未知	先依任務 ID / 素材 ID 查詢，確認未建立再重試
短暫的 `5xx`	服務或能力暫時無法使用	有限次數退避重試，持續失敗時請聯絡平台支援

僅對 429 與短暫的 5xx 重試；400、401、403、404、409 屬於請求或權限問題，重試不會成功。

冪等與重複提交

平台不提供跨介面的自動冪等鍵，請在業務端確保只提交一次：

每次使用者操作先在自有資料庫寫入一筆業務紀錄，再呼叫平台介面；
影片任務與素材提交都要儲存平台傳回的 ID，重試前先查詢是否已建立；
素材處於 Processing 時不要重複提交，否則會建立多份素材；
計費以實際提交成功的任務為準，重複提交會造成重複計費。

建議呼叫順序

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

伺服器端接入建議

為每次請求設定合理的逾時，並區分「逾時」與「使用者取消」；
對 429 與短暫的 5xx 做有限次數的退避重試，其餘錯誤直接回應給呼叫方；
儲存業務請求編號、模型 ID、素材 ID、任務 ID 與平台傳回的請求識別碼，方便排查；
不要將 API Key 寫入日誌、錯誤回報、前端追蹤或截圖；
大型檔案優先使用物件儲存的公開 HTTPS 位址或素材庫 asset:// 參考，不要將大型檔案塞進請求內容。

下一步

想了解什麼	前往哪一頁
有哪些介面	介面總覽
模型目錄與文字對話	模型與文字介面
圖片生成	圖片生成介面
影片生成、多圖與參考影片	影片生成介面
素材分組、素材狀態、真人授權	素材庫介面
報錯怎麼排查	錯誤碼與排查

本頁目錄