快速開始

LocoPal 目前有兩條常用路徑：直接在 LocoPal Creation 創作，或使用 LocoPal Ai 的 API 接入自己的業務。

使用方式	入口	是否需要 API Key	適合場景
直接創作	LocoPal Creation	不需要	圖片、影片、音訊、短劇、素材與作品工作流程
API 接入	LocoPal Ai	需要	把模型、圖片、影片、音訊或素材能力接入既有系統

兩種方式共用同一個 LocoPal 帳戶、模型目錄和計費體系。本頁重點說明 LocoPal Ai 與 LocoPal Creation。

先讀這一條：範例能否跑通取決於 Key 的分組

本頁涵蓋文字、圖片、影片、音訊和素材五類介面，但任何一把 API Key 能呼叫哪些模型，由它所屬的呼叫分組決定。

例如一把只開通「圖像」分組的 Key：GET /v1/models 只傳回圖像模型（如 gpt-image-2.5），此時照抄本頁的文字、影片或音訊範例會得到 503 model_not_found —— 這表示該模型不在你的分組裡，而不是範例寫錯了。

所以：先執行第 5 步，用 /v1/models 看清這把 Key 實際能用什麼，再回來看對應的範例。同一把 Key 在 locopalai.com 與 us-api.locopalai.com 上看到的模型集合可能不同，以你實際使用的位址為準。

第 1 步：註冊或登入 LocoPal Ai

開啟 LocoPal Ai。已有帳號直接登入；沒有帳號時進入註冊頁。
目前註冊頁要求設定使用者名稱和密碼，並完成手機號簡訊驗證。驗證方式可能隨安全策略調整，以註冊頁實際提示為準。
登入後確認帳戶餘額、方案額度或可用點數。使用 Creation 或 API 前都應先確認帳戶可用狀態。

入口	用途
模型廣場	查看模型名稱、能力、參數、價格和可用分組
API 金鑰	建立、停用和查看 API Key
使用日誌	查詢同步呼叫、用量與計費記錄
任務日誌	查詢影片、音訊等非同步任務及成品
素材庫管理	管理虛擬人物素材、真人素材、分組與狀態
錢包	儲值、查看方案、訂單和消費記錄
LocoPal Creation	進入直接創作工作台，不需要建立 API Key

第 2 步：直接使用 LocoPal Creation

如果目標是直接生成內容，推薦先使用 Creation，不需要撰寫程式碼，也不需要建立 API Key。

開啟 LocoPal Creation。
Creation 沒有獨立帳號。未登入時頁面會跳轉到 LocoPal 登入，完成授權後自動返回 Creation，不需要再次輸入密碼。
在首頁選擇智慧模式、AI 繪圖、AI 影片或 AI 音訊並輸入需求；進入工作台後還可以使用短劇、作品、素材、提示詞、詞庫和作品廣場等入口。
需要保持人物、商品或風格一致時，在提交前上傳參考圖或選擇既有素材。
提交後在目前頁面查看任務狀態、預覽結果並下載或繼續引用。重新整理頁面不會重新建立任務，不要對仍在執行的任務重複提交。

Creation 的模型可用範圍和目前 LocoPal Ai 模型目錄保持一致，呼叫消耗統一計入目前 LocoPal 帳戶。模型不可用時，先到 LocoPal Ai 模型廣場確認該模型是否已在目前可用分組中。

第 3 步：接入 API 並建立 API Key

進入 LocoPal Ai 主控台「API 金鑰」並點擊建立。建議按「生產服務 / 測試環境 / 客戶應用」分別建立金鑰，便於依應用查看日誌、限制額度並及時停用外洩的金鑰。

建立時重點確認：

Key 名稱用於區分呼叫方；
呼叫分組決定這把 Key 能看到和呼叫哪些模型；
額度與有效期限用於限制異常消耗；
一把 Key 可呼叫模型、圖片、影片、音訊和素材介面，不需要為不同介面建立不同 Key。

API Key 只保存在伺服器端環境變數或金鑰管理服務中，不要寫入網頁原始碼、行動端安裝檔、公開儲存庫、日誌或截圖。

第 4 步：準備基礎位址

預設基礎位址：

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

平台主控台還可能顯示面向海外模型或特定網路環境的接入位址，例如：

https://us-api.locopalai.com

實際接入時應使用主控台目前顯示的位址。LOCOPAL_BASE_URL 只寫到網域，不要重複附加 /v1；介面路徑本身已經包含 /v1 或 /api/v1。

第 5 步：查詢目前 Key 可用的模型

這一步決定了後面哪些範例能跑

本頁第 6–9 步是四類能力的範例。先跑這一步，看 /v1/models 傳回了什麼，就知道自己有權限用哪幾個範例。沒有傳回的類別不必嘗試 —— 直接跳到模型廣場與計費確認分組，或聯絡平台支援開通。

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

請求裡的 model 必須使用 data[].id，不要使用頁面顯示名稱；
傳回 "data": [] 表示目前 Key 所屬呼叫分組沒有可用模型，先確認分組設定或聯絡平台支援；
模型目錄會隨帳戶授權、接入位址和平台可用性變化，建議在服務啟動、使用者切換模型或收到「模型不可用」時重新查詢；
同一把 Key 在 locopalai.com 與 us-api.locopalai.com 上看到的模型集合可能不同，使用哪個位址就以該位址的 /v1/models 為準；
模型能否呼叫以目前 Key 的 /v1/models 結果為準，不要寫死模型名稱。

用 `supported_endpoint_types` 判斷該用哪個範例

data[].supported_endpoint_types 直接告訴你這個模型走哪類介面，據此選範例即可：

`supported_endpoint_types` 含	走哪個範例	典型介面
`chat` / `openai`（對話類）	第 6 步	`POST /v1/chat/completions`
`image-generation`	第 7 步	`POST /v1/images/generations`
影片類（`video-generation` 等）	第 8 步	`POST /v1/video/generations`
音訊類（`tts` 等）	第 9 步	`POST /v1/audio/speech`

一個模型的 supported_endpoint_types 可能同時含多項，表示它可以用多種介面呼叫。

第 6 步：第一次文字呼叫

调用前请先确认该模型在你的分组内

需要 Key 的分組裡有文字（對話）模型。若該分組只有圖像模型，本步會傳回 503 model_not_found —— 這是分組權限問題，不是請求寫錯了。

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

成功時從 choices[0].message.content 讀取文字，並保存回應裡的 usage 用於對帳。推理模型可能把 max_tokens 全部消耗在 completion_tokens_details.reasoning_tokens，此時 message.content 為空且 finish_reason 為 length；提高輸出上限或改用非推理模型後再試。開啟 stream: true 後按 SSE 逐段讀取，讀到 [DONE] 結束。

第 7 步：第一次圖片呼叫

建议

圖像是獨立的分組權限，與文字、影片、音訊互不影響。只開通圖像分組時，本頁其餘範例都會失敗，但這一步可以正常出圖。

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

回應結果通常在 data[] 中傳回 url 或 b64_json。傳回的 URL 可能是短期位址，應儘快轉存；size、quality 和 response_format 都取決於目前圖片模型，部分 GPT Image 模型會拒絕 response_format 並傳回 unknown_parameter，此時應移除該欄位。圖片作為後續影片參考時，先用素材庫介面入庫並等待狀態為 Active，再使用 asset://<asset_id> 引用。

第 8 步：第一次影片呼叫

调用前请先确认该模型在你的分组内

需要 Key 的分組裡有影片模型。影片、圖像、文字是相互獨立的分組權限：只開通圖像分組時，本步傳回 503 model_not_found，而第 7 步仍然可以出圖。

影片是非同步任務：建立介面傳回任務 ID，查詢介面傳回進度和結果。

POST /v1/video/generations 與 POST /v1/videos 使用同一套請求體和回應格式，任選一種即可；舊呼叫路徑會由平台自動按影片任務外掛處理。

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

{
  "created_at": 1789567067,
  "id": "task-public-id",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task-public-id"
}

建立回應只應依賴 id / task_id、status、model 和 created_at；object、progress 等欄位可能在首次查詢後才出現，不能把它們當作建立成功的必要條件。

保存建立回應裡的 id，再查詢同一個任務：

export LOCOPAL_TASK_ID="创建响应里的 id"

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

任務成功後讀取 metadata.url 下載或播放結果。平台優先傳回上游原始影片 URL；如果上游沒有傳回可讀取位址，才使用平台成品位址備援。上游傳回的影片參數可能包含：

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800
}

以上欄位中，duration_secs 為時長；expires_at 只在對應上游傳回時出現；其他影片參數同樣只在模型和上游實際傳回時出現。取得任務 ID 後即使本機等待逾時，也只能繼續查詢原任務，不要重新建立，否則會產生重複任務和費用。

如果查詢結果 status 為 failed，讀取同一回應裡的 error.code 和 error.message。影片任務終態失敗通常使用 video_generation_failed，error.message 是平台清理後的可讀原因，不要再解析其中的 JSON：

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

第 9 步：第一次文字轉語音呼叫

调用前请先确认该模型在你的分组内

需要 Key 的分組裡有音訊（TTS）模型。本步與圖像分組無關，只開通圖像分組時會傳回 503 model_not_found。

平台提供 OpenAI 相容的 POST /v1/audio/speech 介面。是否可用取決於目前 API Key 的分組和模型目錄；支援的音色、格式與速度參數以實際模型為準。

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

成功回應的正文是二進位音訊，不是 JSON；範例用 --output 保存為 speech.mp3。其他音訊任務的非同步狀態與成品可在「任務日誌」中查詢。

第 10 步：第一次素材呼叫

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

保存 data.group.id，提交圖片並輪詢狀態：

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url 使用可從公網直接下載的 http(s) 位址，也可以按介面限制提交 data_url。data.asset.status 變為 Active 後，即可在影片請求中用 asset://<asset_id> 引用。完整參數與錯誤說明見素材庫介面。

第 11 步：真人素材（選用）

真人素材必須由本人用手機掃碼完成採集和授權，不能用一般圖片上傳代替。主控台流程是「素材庫管理 → 新建分組 → 真人素材 → 產生 QR 碼 → 本人掃碼 → 已完成掃碼，開始同步」；介面流程見建立真人掃碼工作階段。

下一步

想看什麼	去哪一頁
LocoPal Ai 主控台功能	平台功能指南
LocoPal Creation 創作流程	LocoPal Creation（創作平台）
API 平台、分組與任務日誌	LocoPal Ai（API 平台）
有哪些介面	介面總覽
認證、基礎位址、分頁等公共約定	認證與基礎規範
模型目錄與文字對話	模型與文字介面
圖片生成	圖片生成介面
影片生成、多圖與參考影片	影片生成介面
素材分組、素材狀態、真人授權	素材庫介面
端到端接入範例	人像素材與參考影片接入流程
錯誤排查	錯誤碼與排查

本頁目錄