介面總覽

基礎位址統一為 https://locopalai.com，所有介面都使用同一把平台 API Key。共用約定（驗證、回應結構、分頁、限流、冪等）請見驗證與基礎規範。

模型與生成介面

用途	方法	路徑	詳細文件
查詢可用模型	GET	`/v1/models`	模型與文字介面
文字對話（含串流）	POST	`/v1/chat/completions`	模型與文字介面
圖片生成	POST	`/v1/images/generations`	圖片生成介面
文字轉語音	POST	`/v1/audio/speech`	文字轉語音介面
建立影片任務	POST	`/v1/video/generations`	影片生成介面
查詢影片任務	GET	`/v1/video/generations/{task_id}`	影片生成介面
建立影片任務（OpenAI 相容寫法）	POST	`/v1/videos`	影片生成介面
查詢影片任務（OpenAI 相容寫法）	GET	`/v1/videos/{task_id}`	影片生成介面

素材庫介面

素材庫介面全部使用 API Key，成功時統一傳回 { "code": 0, "data": ..., "msg": "..." }。

用途	方法	路徑	詳細文件
查詢素材分組	GET	`/api/v1/materials/groups`	素材分組
建立素材分組（`virtual` / `real`）	POST	`/api/v1/materials/groups`	素材分組
查詢素材清單（支援 `group_id`、分頁）	GET	`/api/v1/materials/assets`	素材
提交圖片素材（`image_url` 或 `data_url`）	POST	`/api/v1/materials/assets`	素材
查詢單一素材狀態	GET	`/api/v1/materials/assets/{asset_id}`	素材
同步素材狀態	POST	`/api/v1/materials/sync`	同步素材狀態
建立真人掃碼授權工作階段	POST	`/api/v1/materials/portrait/sessions`	真人素材授權
確認真人掃碼完成	POST	`/api/v1/materials/portrait/resolve`	真人素材授權

詳細參數、範例與錯誤說明請見素材庫介面總覽。

典型呼叫鏈

模型與影片

GET  /v1/models
  → POST /v1/video/generations
  → GET  /v1/video/generations/{task_id}

建立任務後必須儲存任務 ID；網路中斷時請繼續查詢原任務，不要重複建立。

文字轉語音

GET  /v1/models
  → POST /v1/audio/speech
  → 保存二进制音频响应

音訊介面是否可用、支援哪些 voice 和 response_format，以目前 Key 的模型目錄及實際模型能力為準。

虛擬素材

POST /api/v1/materials/groups
  → POST /api/v1/materials/assets
  → GET  /api/v1/materials/assets/{asset_id}   （轮询到 status 为 Active）
  → 在视频 content 中使用 asset://<asset_id>

真人素材

POST /api/v1/materials/groups {"type":"real"}
  → POST /api/v1/materials/portrait/sessions   （拿到二维码链接）
  → 由真人本人扫码完成采集
  → POST /api/v1/materials/portrait/resolve
  → POST /api/v1/materials/sync
  → 查询素材状态后用于支持真人素材库的模型

端對端範例請見人像素材與參考影片接入流程；多圖與參考影片的能力邊界請見多圖與參考影片說明。

回應與錯誤

介面類型	成功	失敗
模型 / 圖片 / 影片	直接傳回結果物件	HTTP 非 `2xx`，讀取 `error.message`
素材庫	`{ "code": 0, "data": ..., "msg": "OK" }`	HTTP 狀態碼與 `code` 一致

用戶端必須同時檢查 HTTP 狀態與回應內容。完整的錯誤碼與排查方式請見錯誤碼與排查。

本頁目錄