幫助與參考
本頁統一說明文件與平台介面中出現的名詞，避免同一概念在不同頁面出現不同稱呼。
| 術語 | 含義 |
|---|
| LocoPal Ai | API 平台，也是整個生態的核心：帳號、登入、計費、模型目錄、素材庫與任務記錄都由它提供。入口 locopalai.com。 |
| LocoPal Creation | 創作平台（網頁工作台），面向不寫程式的直接創作。入口 creation.locopalai.com。 |
| 主控台 | LocoPal Ai 登入後的管理介面，包含模型廣場、API 金鑰、日誌、素材庫管理、錢包等。 |
| 術語 | 含義 |
|---|
| API keys | 呼叫平台介面的憑證，形式如 sk-...。一把 Key 可呼叫模型、圖片、影片、音訊和素材介面。 |
| Access Token | 短期呼叫權杖。平台前端只將它儲存在記憶體中，不寫入 localStorage。 |
| 更新權杖 / 工作階段 Cookie | 用於在頁面重新整理後還原登入狀態。作用域為 .locopalai.com，因此兩個平台可共用登入。 |
| 統一登入 | 只在 LocoPal Ai 登入一次，其餘平台會自動取得登入狀態。LocoPal Ai 是唯一的身份來源。 |
| 登入狀態失效 | 登出、切換帳號或修改密碼後，兩個平台的工作階段同時失效，需要重新登入。 |
| 術語 | 含義 |
|---|
| 模型 ID | 請求 model 欄位要填的值，來自 GET /v1/models 傳回的 data[].id。不是頁面上顯示的名稱。 |
| 模型廣場 | 查看模型名稱、能力、參數、價格和可用分組的入口。 |
| 呼叫分組 / 分組 | 決定一把 Key 能看到和呼叫哪些模型的授權範圍。一個分組下有若干通道，通道上掛若干模型。 |
| 通道 | 分組下實際承載模型的管道。模型是否可用取決於目前能否路由到可用通道。 |
| 基礎位址（Base URL） | 介面前綴，如 https://locopalai.com。只寫到網域，不要重複附加 /v1。 |
us-api.locopalai.com | 面向海外模型或特定網路環境的備用接入位址。用哪個位址就以該位址的 /v1/models 為準。 |
| 同步呼叫 | 請求傳回時即取得結果的呼叫，如文字、圖片、音訊。 |
| 非同步任務 | 先建立任務取得 ID、再輪詢查詢結果的呼叫，如影片生成。 |
| 術語 | 含義 |
|---|
| 素材庫 | 平台統一的素材儲存空間，依分組組織。入庫一次即可被所有支援素材引用的模型重複使用。 |
| 素材分組 | 素材的容器，分為虛擬（virtual）與真人（real）兩類。 |
| 虛擬素材 | 上傳或生成的圖片素材，適合儲存角色、商品、風格等可重複使用的資料。 |
| 真人素材 | 需由本人用手機掃碼完成活體採集與授權的真人資料，不能用一般圖片上傳替代。 |
| 素材 ID | 素材的唯一識別碼，跨模型保持一致。 |
asset://<asset_id> | 在請求中引用已入庫素材的寫法。需等素材狀態為 Active 後使用。 |
Active | 素材狀態之一，表示素材已處理完成、可穩定用於支援素材引用的模型。 |
Processing | 素材仍在處理中。這不是錯誤，繼續使用同一素材 ID 輪詢即可。 |
data_url | 內嵌提交圖片資料的形式（data:image/...;base64,...），與 image_url 二者只能提交一個。 |
| 術語 | 含義 |
|---|
| 任務 ID | 非同步任務的識別碼。建立後必須儲存，本機逾時也用查詢而不是重建來追蹤。 |
| 任務日誌 | 查看非同步任務執行明細的入口，包含提交時間、任務 ID、耗時、狀態、進度與成品。 |
| 使用日誌 | 查看同步呼叫明細的入口，包含模型、Token 與費用。 |
queued / 排隊中 | 任務已受理，等待執行。 |
processing / 生成中 | 任務執行中，可以離開頁面，稍後回到原記錄查看。 |
succeeded / 已完成 | 結果已生成，可下載或引用。 |
failed / 失敗 | 任務終態失敗。讀取同一回應中的 error.code 與 error.message。 |
video_generation_failed | 影片任務的終態失敗碼，error.message 已是清理後的可讀原因。 |
| 成品 | 任務產物，可直接預覽或下載的圖片、影片、音訊。 |
| 請求快照 | 任務的請求內容與原始請求 JSON。僅管理員可見，一般使用者查詢自己的任務時不會傳回該欄位。 |
| 術語 | 含義 |
|---|
| 按 Token 計費 | 依輸入與輸出 Token 分別計費，單位顯示為 1K 或 1M Token。 |
| 快取輸入 / 快取寫入 | 支援提示詞快取的模型才會顯示的計費項目。 |
| 按次計費 | 每次成功請求依固定價格計費。 |
| 價格矩陣 | 影片模型依「是否含影片輸入」×「輸出解析度」顯示的價格表。 |
| 完成時結算 | 非同步任務的實際扣費發生在任務完成時，提交只受理任務，不預先扣費。 |
| 錢包 | 儲值、方案、訂單與帳單記錄的入口。 |
| 預估消耗 | 任務提交前的費用估算。餘額不足以涵蓋時會直接傳回提示且不會建立任務。 |
| 術語 | 含義 |
|---|
限流 / 429 | 請求過於頻繁。依提示退避重試，不要並行重試。 |
task_concurrency_exceeded | 並行任務達到上限。保留既有任務 ID，等待後再由使用者主動重新提交。 |
| 退避重試 | 失敗後等待一段時間再重試，且逐次延長等待，而不是立即連續重送。 |
| RequestId / 請求 ID | 單次請求的識別碼，排查問題時用於定位具體記錄。 |
400 參數驗證失敗 | 請求未被受理，通常不產生生成任務費用。 |
