KiwiWhale Agent Integration

Quickstart: Generate a Dog

1. Create an agent account with POST /api/v1/agent_register.php.
2. Save the returned API key.
3. Fetch available models with GET /api/v1/models.php.
4. Choose a text-to-image model such as z-image.
5. Submit a job with POST /api/v1/generate.php.
6. Poll GET /api/v1/jobs.php?job_id=... until complete.
7. Read outputs[0].url and use the generated image.

1. Authentication

For agent and hybrid use, send the API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Human browser sessions use normal site login and cookies.

2. Create an Agent Account

Endpoint:

POST /api/v1/agent_register.php

Example request body:

{
  "name": "My Agent"
}

Example response:

{
  "success": true,
  "account_type": "agent",
  "user_id": 123,
  "api_key": "kw_...",
  "credits": 0
}

Important: save the api_key. The agent will need it for all later calls.

3. Check Credits

Endpoint:

GET /api/v1/credits.php

Example response:

{
  "credits": 0,
  "account_type": "agent"
}

4. Discover Available Models

Endpoint:

GET /api/v1/models.php

Agents should use the returned public_model when calling generate.php.

Example response shape:

{
  "success": true,
  "count": 3,
  "models": [
    {
      "product_id": "z-image",
      "public_model": "z-image",
      "category": "text-to-image",
      "cost_credits": 0.05,
      "schema": { ... }
    }
  ]
}

Current Active Models

5. Generate an Image

Endpoint:

POST /api/v1/generate.php

Minimal text-to-image example:

{
  "model": "z-image",
  "prompt": "a realistic dog sitting in a park"
}

Example success response:

{
  "status": "queued",
  "job_id": "abc123",
  "auto_topup_applied": false,
  "auto_topup_message": ""
}

Generation is asynchronous. A successful submit returns a job_id, not the final image.

6. Poll Job Status

Endpoint:

GET /api/v1/jobs.php?job_id=abc123

Example completed response:

{
  "status": "completed",
  "outputs": [
    {
      "url": "https://...",
      "mime": "image/png"
    }
  ],
  "seed": 12345
}

Agents should keep polling until status is one of:

completed, succeeded, success, done, finished

Then use outputs[0].url.

7. Billing and Auto Top-Up

KiwiWhale uses credits as the wallet unit.

• If enough credits exist, generation proceeds immediately.
• If credits are low and auto top-up is configured, KiwiWhale may top up before generation continues.
• The response may include auto_topup_applied and auto_topup_message.

Payment Method Setup

First-time autonomous payment setup uses these endpoints:

POST /api/v1/agent_setup_payment.php
POST /api/v1/agent_confirm_payment_method.php

In practice, the first payment method setup may require browser interaction. After setup, off-session charging can be autonomous.

Manual Autonomous Top-Up

POST /api/v1/agent_topup.php

{
  "credits": 10
}

8. Full Example: Create a Dog Image

Step A — Register

POST /api/v1/agent_register.php

{
  "name": "Dog Image Agent"
}

Step B — Save the API key

api_key = "kw_..."

Step C — Discover models

GET /api/v1/models.php
Authorization: Bearer kw_...

Step D — Choose a text-to-image model

model = "z-image"

Step E — Submit generation

POST /api/v1/generate.php
Authorization: Bearer kw_...
Content-Type: application/json

{
  "model": "z-image",
  "prompt": "a realistic dog sitting in a park"
}

Step F — Poll job

GET /api/v1/jobs.php?job_id=...
Authorization: Bearer kw_...

Step G — Use result

outputs[0].url

9. OpenClaw / Browser Automation Notes

For full first-time autonomous onboarding, an automation agent may:

1. Register the agent account
2. Save the API key
3. Open the payment setup page
4. Fill Stripe card fields
5. Save the payment method
6. Call generate.php
7. Poll jobs.php

This is why KiwiWhale also provides automation-friendly pages and selectors for browser agents.

10. Common Errors

{
  "error": "INSUFFICIENT_CREDITS",
  "message": "Not enough credits to run this request."
}

{
  "error": "payment_method_not_ready",
  "message": "No saved off-session payment method is configured."
}

{
  "error": "Unknown or inactive model"
}

Agents should treat error codes and messages as part of normal control flow.