B2B API 控制台
在一个页面里查看和测试 KusArt 生成接口
集中查看 B2B 任务接口、必填参数、响应结构、curl 示例、扣费逻辑、轮询方式和 Webhook 回调流程。
接入基础
认证方式
所有 B2B 路由都使用 X-API-Key 请求头，不需要 Web 端的 Firebase token。
扣费方式
带 billing_account_id 的旧 Key 继续从指定积分账户扣费；新的用户维度 Key 从用户积分池冻结。
响应格式
业务响应统一使用 code/message/data。业务错误也可能返回 HTTP 200。
完整调用流程
task-create、积分冻结、轮询、结果获取和 webhook 回调在后端如何串起来。
1
创建任务
合作方携带 X-API-Key 和任务参数调用 B2B 创建接口。
2
认证 Key
后端校验 API Key，并注入所属用户和可选的专属积分账户。
3
冻结积分
Worker 计算成本，并从专属积分账户或用户积分池冻结积分。
4
执行任务
对应 Worker 调用内部能力或外部模型 API，并保存任务产物。
5
获取结果
合作方轮询 /tasks/get 或 /tasks/get_result，直到任务完成或失败。
6
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 或所属用户没有足够可用积分来冻结本次任务成本。