KusArt
    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.

    1

    Create

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

    2

    Authenticate

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

    3

    Freeze credits

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

    4

    Execute

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

    5

    Get result

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

    6

    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.