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 } ] } } }