B2B API console

Build and test KusArt generation APIs in one place

Review the supported B2B task interfaces, required parameters, response envelopes, curl examples, billing behavior, polling, and webhook delivery flow.

Manage API keys

Integration basics

Authentication

All B2B routes use the X-API-Key header. Firebase web tokens are not required for these routes.

Billing

Legacy keys with billing_account_id use that dedicated credit account. New user-scoped keys freeze from the user credit pool.

Response envelope

Business responses use code/message/data. Business errors may still return HTTP 200.

End-to-end call flow

How task-create, credit freezing, polling, results, and webhook callbacks fit together.

Create

Partner sends X-API-Key plus task parameters to a B2B create endpoint.

Authenticate

Backend validates the API key and attaches the owning user plus optional billing account.

Freeze credits

Worker calculates cost and freezes credits from the dedicated account or user credit pool.

Execute

The selected worker calls internal or external generation capability and stores task output.

Get result

Partner polls /tasks/get or /tasks/get_result until the task is completed or failed.

Webhook

If webhook_url is supported and provided, backend POSTs the final task payload and settles credits.

Auth header

Use the raw API key directly in X-API-Key.

X-API-Key: ak_xxx

Credit freeze

B2B tasks freeze before execution.

If the API key has a target billing account, credits freeze there. Otherwise the freeze falls back to the user's available credit accounts. Insufficient balance should return code 42002.

Standard response

code = 0 means success. Non-zero codes should be handled as business errors.

{
  "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
    }
  }
}

Polling response

Use /tasks/get for status and progress, or /tasks/get_result when only the final result is needed.

{
  "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

Webhook delivery posts JSON to your URL on completion or failure. The server retries up to 3 total attempts.

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

Common business codes

The API response code is the stable integration contract; do not rely only on HTTP status.

0

Success

Request accepted or data returned successfully.

40000

Invalid parameters

JSON body, task params, files, or URLs are invalid.

40100

Unauthorized

Missing or invalid authentication context.

42002

Insufficient balance

The API key or user does not have enough available credits to freeze the task cost.

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