B2B API 控制台

在一個頁面裡檢視和測試 KusArt 生成介面

集中檢視 B2B 任務介面、必填參數、響應結構、curl 示例、扣費邏輯、輪詢方式和 Webhook 回撥流程。

管理 API Key

接入基礎

認證方式

所有 B2B 路由都使用 X-API-Key 請求頭，不需要 Web 端的 Firebase token。

扣費方式

帶 billing_account_id 的舊 Key 繼續從指定積分帳戶扣費；新的使用者維度 Key 從使用者積分池凍結。

響應格式

業務響應統一使用 code/message/data。業務錯誤也可能返回 HTTP 200。

完整呼叫流程

task-create、積分凍結、輪詢、結果獲取和 webhook 回撥在後端如何串起來。

建立任務

合作方攜帶 X-API-Key 和任務參數呼叫 B2B 建立介面。

認證 Key

後端校驗 API Key，並注入所屬使用者和可選的專屬積分帳戶。

凍結積分

Worker 計算成本，並從專屬積分帳戶或使用者積分池凍結積分。

執行任務

對應 Worker 呼叫內部能力或外部模型 API，並儲存任務產物。

獲取結果

合作方輪詢 /tasks/get 或 /tasks/get_result，直到任務完成或失敗。

Webhook

如果介面支援並傳入 webhook_url，後端會在最終狀態時 POST 回撥並完成積分結算。

認證請求頭

直接把原始 API Key 放到 X-API-Key。

X-API-Key: ak_xxx

積分凍結

B2B 任務會在執行前凍結積分。

如果 API Key 綁定了 target billing account，會從該帳戶凍結；否則回退到使用者可用積分帳戶池。餘額不足時應返回 code 42002。

標準響應

code = 0 表示成功；非 0 code 應按業務錯誤處理。

{
  "code": 0,
  "message": "Success",
  "data": {
    "task_id": "00000000-0000-0000-0000-000000000000",
    "status": "PENDING",
    "queue_position": 2,
    "generation_params": {
      "prompt": "anime engineer debugging an API dashboard",
      "watermark": false
    }
  }
}

輪詢響應

需要狀態和進度時用 /tasks/get；只關心最終結果時用 /tasks/get_result。

{
  "code": 0,
  "message": "Success",
  "data": {
    "task_id": "00000000-0000-0000-0000-000000000000",
    "task_type": "API_TEXT_TO_IMAGE_GPT_IMAGE_2",
    "status": "COMPLETED",
    "result": {
      "images": [
        {
          "display_url": "https://cdn.kusa.pics/generated/example.png",
          "width": 1024,
          "height": 1024,
          "index": 0
        }
      ],
      "image_count": 1
    }
  }
}

Webhook payload

任務完成或失敗時，後端會向你的 URL POST JSON；目前最多嘗試 3 次。

{
  "code": 0,
  "data": {
    "task_id": "00000000-0000-0000-0000-000000000000",
    "status": "COMPLETED",
    "result": {
      "images": [
        {
          "display_url": "https://cdn.kusa.pics/generated/example.png",
          "width": 1024,
          "height": 1024,
          "index": 0
        }
      ]
    }
  }
}

常見業務碼

API 的 code 才是穩定接入契約，不要只依賴 HTTP status。

0

成功

請求已接受，或資料已成功返回。

40000

參數錯誤

JSON、任務參數、檔案或 URL 不合法。

40100

未認證

缺少或無法識別認證上下文。

42002

餘額不足

API Key 或所屬使用者沒有足夠可用積分來凍結本次任務成本。

{ "code": 0, "message": "Success", "data": { "task_id": "00000000-0000-0000-0000-000000000000", "status": "PENDING", "queue_position": 2, "generation_params": { "prompt": "anime engineer debugging an API dashboard", "watermark": false } } }

{ "code": 0, "message": "Success", "data": { "task_id": "00000000-0000-0000-0000-000000000000", "task_type": "API_TEXT_TO_IMAGE_GPT_IMAGE_2", "status": "COMPLETED", "result": { "images": [ { "display_url": "https://cdn.kusa.pics/generated/example.png", "width": 1024, "height": 1024, "index": 0 } ], "image_count": 1 } } }

{ "code": 0, "data": { "task_id": "00000000-0000-0000-0000-000000000000", "status": "COMPLETED", "result": { "images": [ { "display_url": "https://cdn.kusa.pics/generated/example.png", "width": 1024, "height": 1024, "index": 0 } ] } } }