LumiProxyApi 技術串接整理

BytePlus Lumina「一鍵部署能力」的通用 API 整理：能否用 API 呼叫 AI 模型、如何取得模型、提供哪些 API 功能。

結論：可以，但採「工作流部署」模式

LumiProxyApi 呼叫的是你部署在 Lumina 的工作流能力（req_key），而非直接指定模型名稱。流程：智能畫布建立工作流（節點選用 Seedream／Seedance 等模型）→ 開槽 → 一鍵部署 → API 呼叫。

門檻：一鍵部署僅限特定訂閱套餐，運算資源（資源日曆）需預先申請。

四大 AI 功能支援度速覽

text-to-image 文生圖支援 Seedream 5.0／4.5／4.0、Nano Banana Pro、GPT Image 2 text-to-video 文生影片支援 Seedance 2.0 Pro／1.5 Pro／1.0 系列、Video Unified Model O1 image-to-video 圖生影片支援 Seedance 系列（含首尾幀模式）、Video Unified Model O1 video-to-video 影生影片部分支援無獨立 v2v 模式，可經「影片編輯／延伸」達成

服務架構與運作模式

LumiProxyApi 提供企業級演算法服務的通用接入能力：非同步任務提交、同步處理、結果查詢、任務取消。它代理的是「你部署的工作流能力」，而非單一模型。

在 Lumina 建立工作流於智能畫布新建、套用模板或匯入工作流檔案；節點中選用 AI 模型。
參數定義（開槽，Slotting）指定對外開放的節點參數，成為 API 的 req_json 欄位；文生圖／圖生圖務必建立輸入、輸出圖片槽位。
一鍵部署工作流跑通後啟用自動部署，發佈為演算法服務並命名「能力名稱」。
能力與資源接入控制台「Abilities and resources」取得 req_key（Ability name）與 res_quota_name（Resource name）；服務詳情頁有開槽參數與 demo。
透過 LumiProxyApi 呼叫簽名後向 cv.byteplusapi.com 發送：同步用 LumiProcess；非同步用 LumiSync2AsyncSubmitTask + LumiSync2AsyncBatchGetResults。

使用門檻

一鍵部署僅限特定訂閱套餐；資源日曆需以算點兌換、預先申請，目前需線下聯繫技術支援設定。導入前先確認套餐與配額。

如何取得目前提供的 AI Model

沒有「列出模型」的 API 端點

模型在 Lumina 平台的工作流節點中選用；API 能呼叫的是「已部署能力（req_key）」，能力背後綁定建立工作流時所選的模型組合。

層面	位置	說明
模型清單	Lumina 平台	於畫布生成節點的「基礎模型（Foundation Model）」選單查看與選用；陣容由官方持續更新。
API 能力清單	控制台「Abilities and resources」頁	Ability name＝`req_key`、Resource name＝`res_quota_name`；服務詳情頁有開槽參數與 demo 範例。

文件記載的模型陣容

整理自官方 Lumina Introduction 與 Canvas User Guide（2026-06-11），實際以平台內顯示為準。

類別	模型	生成模式
圖片生成	Seedream 5.0／4.5／4.0（自研）；Nano Banana Pro、GPT Image 2（第三方）	文生圖、圖生圖、多圖輸入、組圖生成（最多 9 張）、指令式編輯
影片生成	Seedance 2.0 Pro、1.5 Pro、1.0 系列（自研）；Video Unified Model O1	文生影片、圖生影片、首尾幀；O1 另支援主體參考、影片編輯、多幀編輯；1.5 系列支援音畫同步；2.0 支援多模態素材參考與影片編輯、延伸
其他	音訊生成、數位人等多模態模型	畫布提供文字／圖片／影片／音訊生成節點與腳本生成

AI 功能支援度分析

功能	支援度	對應模型／能力	經 API 使用方式
`text-to-image`	支援	Seedream 5.0／4.5／4.0、Nano Banana Pro、GPT Image 2	文生圖工作流（建立輸出圖片槽位）→ 部署 → 呼叫；官方部署文件明示 txt2img 範例。
`image-to-image`	支援	同上	官方明示 img2img 範例；圖片以 `binary_data`（Base64）或 `data_source`（URL）傳入。
`text-to-video`	支援	Seedance 2.0 Pro／1.5 Pro／1.0、Video Unified Model O1	平台支援文生影片；畫布含影片生成節點，工作流可部署為 API 能力（見下方注意事項）。
`image-to-video`	支援	Seedance 系列（圖生影片、首尾幀）、O1（含主體參考）	同上；輸入圖經 `binary_data` 或 `data_source` 傳入。
`video-to-video`	部分支援	O1「影片編輯」（換主體／風格／特效）、多幀編輯；Seedance 2.0 影片編輯與延伸；畫布影片編輯節點（裁切、字幕擦除、取幀、拼接）	無獨立 v2v 模式，以「匯入影片＋影片編輯」工作流達成；此類工作流能否開槽部署為 API 官方未明文展示，建議向技術支援確認。

影片類功能經 API 使用的注意事項

API 鏈路支援影片素材：介面總覽註明適用「圖片等多媒體資料」，且錯誤碼含影片審核（23006／23007）與音訊審核（23008／23009）。官方範例皆以圖片為主（binary_data 限 8MB），影片實務上應以 data_source URL 傳入、產出經 resp_json 回傳。推測後半段為依文件結構之推論，請以實測為準。
替代方案：只需影片生成模型的直接 API 時，可評估 Dreamina Seedance 2.0 官方 API 或 BytePlus ModelArk 產品線。

接入前準備與認證

於 IAM 金鑰管理建立 AccessKey／SecretKey。
接入 BytePlus SDK，依官方簽名方法計算簽名，置於 Authorization 標頭。
完成工作流部署，取得 req_key 與 res_quota_name。

共通請求資訊

四個 API 共用以下設定，僅 Action 與 Body 參數不同。官方範例另帶 get-svc: 1 標頭（用途未說明）。

項目	值	說明
`cv.byteplusapi.com`	POST	請求網域；所有介面均用 POST
Query `Action`	各介面名稱	見 API 總覽
Query `Version`	`2025-06-01`	介面版本，固定值
Header `ServiceName`	`cv`	必填
Header `Region`	`ap-singapore-1`	必填
Header `Authorization`	簽名金鑰	必填，依官方簽名方法計算
Header `Content-Type`	`application/json`	必填

API 總覽

共 4 個介面；除輕量任務外，官方建議優先採用非同步。

Action	模式	用途
`LumiSync2AsyncSubmitTask`	非同步	提交任務，回傳 `task_id`
`LumiProcess`	同步	直接回傳結果（預設逾時 30 秒）
`LumiSync2AsyncBatchGetResults`	非同步	以 `task_id` 批次查詢狀態與結果
`LumiSync2AsyncBatchCancelTasks`	非同步	批次取消未開始的任務

提交非同步任務

POST ?Action=LumiSync2AsyncSubmitTask&Version=2025-06-01

提交非同步處理任務，支援圖片 Base64 或公網可存取 URL，回傳任務 ID；後續以查詢介面輪詢結果。

Body 參數（SubmitTaskReq）

參數名	類型	必填	說明
`req_key`	string	必填	請求唯一識別碼，即一鍵部署自訂的能力名稱（Ability name）
`res_quota_name`	string	必填	資源名稱（Resource name）；填錯回錯誤碼 `10002`
`req_json`	json	必填	業務參數，即「開槽」開放的演算法參數；欄位定義見服務詳情，demo 有實例
`binary_data`	[]string	選填	圖片 Base64 列表；與 `data_source` 二選一、至少傳其一。單張限 8MB，超出回 `400, Error when parsing request`
`data_source`	[]*common.DataSource	選填	資料來源連結列表（HTTP／HTTPS，需可下載，否則回參數錯誤）
`expired_duration`	*int64	選填	任務過期時間（毫秒），預設依服務配置

DataSource 結構

參數名	類型	必填	說明
`data_source_type`	int64	必填	預設填 `1`
`value`	string	必填	可下載的 URL；連結黑名單域名以官方規範為準

回應參數（SubmitTaskResp）

參數名	類型	說明
`task_id`	string	任務 ID（用於查詢或取消）
`resp_json`	string	初步回應結果（可能含前置處理資訊）

請求範例

Shell

curl --location 'http://cv.byteplusapi.com?Action=LumiSync2AsyncSubmitTask&Version=2025-06-01' \
--header 'Authorization: YOURAuthorization' \
--header 'Region: ap-singapore-1' \
--header 'ServiceName: cv' \
--header 'Content-Type: application/json' \
--header 'get-svc: 1' \
--data '{
    "req_key": "hy_test_lumi_onedeploy_mingxinp_v1",
    "req_json": {
        "input_text": "HELLO",
        "seed": 1,
        "input_image": "uri://binary_data?index=0"
    },
    "binary_data": [
        "PIC1 base64"
    ]
}'

Shell

curl --location 'http://cv.byteplusapi.com?Action=LumiSync2AsyncSubmitTask&Version=2025-06-01' \
--header 'Authorization: YOURAuthorization' \
--header 'Region: ap-singapore-1' \
--header 'ServiceName: cv' \
--header 'Content-Type: application/json' \
--header 'get-svc: 1' \
--data '{
    "req_key": "hy_test_lumi_onedeploy_mingxinp_v1",
    "req_json": {
        "input_text": "HELLO",
        "seed": 1,
        "input_image": "uri://binary_data?index=0"
    },
    "data_source": [
        {
            "data_source_type": 1,
            "value": "Picture url"
        }
    ]
}'

回應範例

JSON

{
    "code": 0,
    "message": "",
    "data": {
        "task_id": "14468076912309597066",
        "resp_json": ""
    },
    "request_id": "202506031700371C156D18803F25334BFC"
}

同步處理

POST ?Action=LumiProcess&Version=2025-06-01

同步呼叫演算法，回應直接帶回結果，適用輕量任務。

預設逾時 30 秒

超過 30 秒回傳失敗；官方建議優先採用非同步。生成類任務通常耗時較長，實務上建議一律走非同步。

Body 參數（ProcessReq）

與 SubmitTask 相同（無 expired_duration）：

參數名	類型	必填	說明
`req_key`	string	必填	能力名稱
`res_quota_name`	string	必填	資源名稱
`req_json`	json	必填	業務參數（開槽參數）
`binary_data`	[]string	選填	圖片 Base64 列表（與 `data_source` 二選一、至少其一）
`data_source`	[]*common.DataSource	選填	資料來源連結列表（結構同 DataSource）

回應參數（AlgoResp）

參數名	類型	說明
`binary_data`	[][]byte	二進位結果（如處理後的圖檔）
`resp_json`	string	JSON 演算法結果（核心業務資料）

請求範例

以 data_source 傳 URL 的寫法與提交非同步任務相同，僅 Action 不同。

Shell

curl --location 'http://cv.byteplusapi.com?Action=LumiProcess&Version=2025-06-01' \
--header 'Authorization: YOURAuthorization' \
--header 'Region: ap-singapore-1' \
--header 'ServiceName: cv' \
--header 'Content-Type: application/json' \
--header 'get-svc: 1' \
--data '{
    "req_key": "hy_test_lumi_onedeploy_mingxinp_v1",
    "req_json": {
        "input_text": "HELLO",
        "seed": 1,
        "input_image": "uri://binary_data?index=0"
    },
    "binary_data": [
        "PIC1 base64"
    ]
}'

回應範例

JSON

{
    "code": 0,
    "message": "",
    "request_id": "2025060316510263209B2543B40032B4A0",
    "data": {
        "binary_data": ["return PIC1base64", "return PIC2base64"],
        "resp_json": "{\"output_image\": [\"uri://binary_data?index=0\"], \"comfyui_cost\": 0}"
    }
}

批次查詢任務結果

POST ?Action=LumiSync2AsyncBatchGetResults&Version=2025-06-01

以任務 ID 批次查詢非同步任務的狀態與結果。

Body 參數（GetResultReq）

參數名	類型	必填	說明
`task_ids`	[]string	必填	待查詢的任務 ID 列表

回應參數（BatchGetResultResp → GetResultRespV2）

results 為 []*GetResultRespV2，欄位如下：

參數名	類型	說明
`task_id`	string	任務 ID
`status`	string	任務狀態，見任務狀態枚舉
`progress`	int64	進度 0–100（僅非同步任務回傳）
`req_json`	string	提交時的原始業務參數
`submit_timestamp_ms`	int64	提交時間（毫秒時間戳）
`process_start_timestamp_ms`	int64	開始處理時間（毫秒時間戳）
`process_end_timestamp_ms`	int64	結束時間（毫秒時間戳，完成後回傳）
`algo_status_code`	int32	演算法狀態碼
`algo_status_message`	string	演算法錯誤訊息（失敗時回傳）
`status_code`	int32	錯誤碼（0 成功，非 0 見錯誤碼）
`status_message`	string	狀態資訊

先看 status，再看 algo_status_code

僅 status 為 done 時才依 algo_status_code 判讀結果；其餘狀態下 StatusCode 無效。

請求範例

Shell

curl --location 'http://cv.byteplusapi.com?Action=LumiSync2AsyncBatchGetResults&Version=2025-06-01' \
--header 'Authorization: YOURAuthorization' \
--header 'Region: ap-singapore-1' \
--header 'ServiceName: cv' \
--header 'Content-Type: application/json' \
--header 'get-svc: 1' \
--data '{
    "task_ids": ["14468076912309597066"]
}'

回應範例

JSON

{
    "code": 0,
    "message": "",
    "data": {
        "results": [
            {
                "binary_data": [],
                "resp_json": "{\"output_image\": [\"uri://binary_data?index=0\"], \"comfyui_cost\": 133}",
                "status": "done",
                "callback_args": "",
                "progress": 0,
                "req_json": "{\"input_image\":\"uri://binary_data?index=0\",\"input_text\":\"HELLO\",\"seed\":13}",
                "task_id": "14468076912309597066",
                "submit_timestamp_ms": 1748941238332,
                "process_start_timestamp_ms": 1748941238388,
                "process_end_timestamp_ms": 1748941252489,
                "req_key": "hy_test_lumi_onedeploy_mingxinp_v1",
                "algo_status_code": 0,
                "algo_status_message": " <- [返回]消息=Success:Success",
                "status_code": 0
            }
        ]
    },
    "request_id": "202506031700531C156D18803F2533520C"
}

批次取消任務

POST ?Action=LumiSync2AsyncBatchCancelTasks&Version=2025-06-01

批次取消尚未開始處理的任務；已開始處理者無法取消，會列於 failed_task_ids。

Body 參數與回應

參數名	位置	類型	說明
`task_ids`	請求	[]string	待取消的任務 ID 列表（必填）
`failed_task_ids`	回應	[]string	取消失敗的任務 ID（通常因已開始處理）

請求範例

Shell

curl --location 'http://cv.byteplusapi.com?Action=LumiSync2AsyncBatchCancelTasks&Version=2025-06-01' \
--header 'Authorization: YOURAuthorization' \
--header 'Region: ap-singapore-1' \
--header 'ServiceName: cv' \
--header 'Content-Type: application/json' \
--header 'get-svc: 1' \
--data '{
    "task_ids": ["14468076912309597066"]
}'

回應範例

JSON

{
    "code": 0,
    "message": "",
    "data": {
        "failed_task_ids": []
    },
    "request_id": "202506031713241DA91B56FDF0AA32030D"
}

任務狀態枚舉

狀態	說明
in_queue	任務已提交，排隊中
generating	任務已被消費，處理中
done	處理完成；僅此狀態下依 `algo_status_code` 判讀結果
not_found	無此任務，或任務已過期（24 小時）
expired	已達設定的過期時間（`expired_duration`）
canceled	任務已被取消
over_max_retries	已達最大重試次數

請求規範與注意事項

JSON 欄位大小寫須與文件一致（req_key 而非 ReqKey），缺少 req_key／req_json 回錯誤碼 10004。
Base64 不含 data:image/... 前綴；data_source URL 須公網可下載，並遵守官方連結黑名單規範。

附件與 req_json 的索引對應

req_json 中的 uri://binary_data?index=0 指向 binary_data 列表的第 0 個檔案。改用 data_source 傳 URL 時，系統會先下載轉為 binary_data 再依相同 index 對應——兩種傳法的 req_json 寫法一致。

實務建議

生成類任務通常逾 30 秒，建議一律非同步：SubmitTask → 輪詢 BatchGetResults（以 progress 顯示進度）。
任務結果保留 24 小時，完成後請及時取回轉存。
輸入輸出皆經平台審核（文字／圖片／影片／音訊），需處理 23xxx 失敗分支；遇 11000／11001 限流採指數退避重試。

錯誤碼對照

0 表示成功；其餘依分組查照。點擊分組展開明細。

內部錯誤（10xxx／30402） 6 項

StatusCode	StatusMessage	說明
`10000`	Internal Error	閘道呼叫演算法服務報錯，常見為逾時
`10001`	RPC Internal Error	下游演算法服務異常（子服務逾時、服務崩潰等）
`10002`	Downstream RPC Service No Targets Found Error	閘道未發現下游實例；請檢查 `res_quota_name` 是否正確
`10003`	ECRetryInternal	閘道重試後仍因逾時等原因失敗
`10004`	—	缺少 `req_key`／`req_json`，回 `input validate failed` 欄位驗證錯誤
`30402`	ErrCodeBizError	服務異常，請聯繫官方技術支援

限流錯誤（11xxx） 2 項

StatusCode	StatusMessage	說明
`11000`	Req over limit	觸發閘道限流，多因演算法資源不足
`11001`	ECReqConFailed	單實例 BACKLOG 限流，連線失敗（如 1115）

輸入錯誤（2xxxx／304xx） 8 項

StatusCode	StatusMessage	說明
`20000`	RPC Process Error: {err_msg}…	演算法識別的非通用輸入錯誤
`21000`／`30432`／`30400`	Invalid Param	參數錯誤
`30404`	FeatNotFound	能力不存在
`21001`／`30431`	Image Decode Error	圖片解碼錯誤
`21002`	Image Empty	傳入圖片為空
`21003`	Invalid Image	傳入圖片演算法無法處理
`22000`	No Face Detected	未偵測到人臉
`22001`	No Man Detected	未偵測到人

審核錯誤（23xxx） 14 項

審核涵蓋文字／圖片／影片／音訊／版權——佐證 API 鏈路支援影音素材的輸入輸出。

StatusCode	StatusMessage	說明
`23001`	Pre Img Risk Not Pass	輸入圖片前審核未通過
`23002`	Post Img Risk Not Pass	輸出圖片後審核未通過
`23003`	Text Risk Not Pass	輸入文字前審核未通過
`23004`	Post Text Risk Not Pass	輸出文字後審核未通過
`23005`	Post Text Risk Not Pass	敏感詞服務攔截（多用於版權詞審核）
`23006`	Pre Video Risk Not Pass	輸入影片前審核未通過
`23007`	Post Video Risk Not Pass	輸出影片後審核未通過
`23008`	Pre Audio Risk Not Pass	輸入音訊前審核未通過
`23009`	Post Audio Risk Not Pass	輸出音訊後審核未通過
`23010`	Pre Image Copyright Not Pass	輸入版權圖前審核未通過
`23011`	Post Image Copyright Not Pass	輸出版權圖後審核未通過
`23100`	ECRiskInternal	審核服務異常
`23101`	ECAntidirtInternal	版權詞服務異常
`23102`	ECImgCopyrightInternal	版權圖服務異常

鑑權錯誤（24xxx／30403） 6 項

StatusCode	StatusMessage	說明
`24000`	Ability Auth failed	能力層級認證未通過
`30403`	NoFeatAuth	沒有該能力的權限
`24001`	Application Auth failed	通用認證未通過
`24002`	Sign Auth failed	簽名錯誤
`24003`	Authorization failed	存取授權未通過
`24004`	SignAuth Time Expired	驗簽時間戳過期

參考資料

LumiProxyApi Integration Document（更新：2026-04-16）
One-click Deployment ・ Lumina Introduction（更新：2026-06-11）・ Canvas User Guide
簽名計算方法・ IAM 金鑰管理

本頁為第三方整理（2026-06-11，所有關鍵事實已逐項核對官方文件）。API 規格與模型陣容可能變動，串接前請以官方文件為準；標註推測處為合理推論、未經實測。