> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Estimate a job, submit it, poll for the result and read your usage.

**1. Check your key and balance**

Create an API key in the [developer console](https://blon.ai/console/keys) and send it as a Bearer token. See [Authentication](https://docs.blon.ai/authentication.md).

```bash theme={null}
curl https://api.blon.ai/v1/balance \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "currency": "USD",
  "available": "18.425",
  "held": "0.0042",
  "usage_this_month": "1.5708",
  "spend_limit": {
    "amount": "50.00",
    "spent": "1.5708",
    "window": "month",
    "resets_at": "2026-11-01T00:00:00.000Z"
  }
}
```

**2. Estimate**

An estimate charges nothing and creates no job. It returns the amount Blon would hold if you submitted the same request now.

```bash theme={null}
curl https://api.blon.ai/v1/estimate \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"}}'
```

```json theme={null}
{
  "model": "gpt-image-2",
  "cost": {
    "currency": "CREDITS",
    "amount": "8"
  },
  "kind": "exact",
  "reason": null
}
```

**3. Submit a job**

`POST /jobs` answers `202 Accepted` with the job. Send an `Idempotency-Key` so a retry cannot create a second job.

```bash theme={null}
curl https://api.blon.ai/v1/jobs \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"},"webhook_url":"https://example.com/hooks/blon","metadata":{"order":"A-17"}}'
```

```json theme={null}
{
  "id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "object": "job",
  "model": "gpt-image-2",
  "status": "queued",
  "provider_status": null,
  "queue_position": null,
  "cancelable": true,
  "next_poll_after_seconds": 5,
  "urls": {
    "get": "https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e",
    "cancel": "https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e/cancel"
  },
  "input": {
    "prompt": "A ceramic teapot on a linen table, soft morning light"
  },
  "metadata": {
    "order": "A-17"
  },
  "cost": {
    "currency": "CREDITS",
    "estimated": "8",
    "charged": null,
    "refunded": "0"
  },
  "usage": null,
  "artifacts": null,
  "expires_at": null,
  "error": null,
  "webhook": {
    "url": "https://example.com/hooks/blon",
    "status": "pending",
    "attempts": 0
  },
  "idempotency_hit": false,
  "request_id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "created_at": "2026-10-30T08:00:00.000Z",
  "started_at": null,
  "completed_at": null,
  "updated_at": "2026-10-30T08:00:00.000Z"
}
```

**4. Poll for the result**

Read the job until `status` is `completed`, `failed` or `canceled`. Wait at least `next_poll_after_seconds` between reads. A completed job lists its files in `artifacts`.

```bash theme={null}
curl https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "object": "job",
  "model": "gpt-image-2",
  "status": "completed",
  "provider_status": "succeeded",
  "queue_position": null,
  "cancelable": false,
  "next_poll_after_seconds": null,
  "urls": {
    "get": "https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e",
    "cancel": null
  },
  "input": {
    "prompt": "A ceramic teapot on a linen table, soft morning light"
  },
  "metadata": {
    "order": "A-17"
  },
  "cost": {
    "currency": "CREDITS",
    "estimated": "8",
    "charged": "8",
    "refunded": "0"
  },
  "usage": null,
  "artifacts": [
    {
      "id": "cmh2x0g2p0002qv8zb3n5k8wd",
      "name": "default",
      "type": "image",
      "url": "https://blon.ai/api/assets/cmh2x0g2p0002qv8zb3n5k8wd?ticket=…",
      "url_expires_at": "2026-10-30T08:15:00.000Z",
      "content_type": "image/png",
      "size_bytes": 1482113,
      "width": 1024,
      "height": 1024,
      "duration_ms": null
    }
  ],
  "expires_at": "2026-11-06T08:00:00.000Z",
  "error": null,
  "webhook": {
    "url": "https://example.com/hooks/blon",
    "status": "delivered",
    "attempts": 1
  },
  "idempotency_hit": false,
  "request_id": "cmh2x0f6k0001qv8z9d4c1a7e",
  "created_at": "2026-10-30T08:00:00.000Z",
  "started_at": "2026-10-30T08:00:01.000Z",
  "completed_at": "2026-10-30T08:00:09.000Z",
  "updated_at": "2026-10-30T08:00:09.000Z"
}
```

**5. Read your usage**

Usage groups settled jobs by UTC time bucket, model and key, over at most 31 days. It is a usage report, not an invoice.

```bash theme={null}
curl "https://api.blon.ai/v1/usage?timeframe=day" \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "currency": "USD",
  "timeframe": "day",
  "start": "2026-10-24T00:00:00.000Z",
  "end": "2026-10-31T00:00:00.000Z",
  "data": [
    {
      "bucket_start": "2026-10-30T00:00:00Z",
      "model": "gpt-image-2",
      "api_key_id": "key_7d2f9a",
      "jobs": 12,
      "units": {
        "output_images": 12
      },
      "cost": "0.48"
    }
  ]
}
```

> [!NOTE]
>
> Amounts are in the caller's wallet currency. A `blon_api_` key always gets `USD`; the job and estimate examples on this page show `CREDITS`, which is what the CLI and MCP see.

## Next steps

> [card] [Requests](https://docs.blon.ai/concepts/requests.md)
>
> Job statuses and fields.

> [card] [Webhooks](https://docs.blon.ai/how-to/webhooks.md)
>
> Get notified instead of polling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.