Quickstart

curl https://api.blon.ai/v1/balance \
  -H "Authorization: Bearer $BLON_API_KEY"

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

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

{
  "model": "gpt-image-2",
  "cost": {
    "currency": "CREDITS",
    "amount": "8"
  },
  "kind": "exact",
  "reason": 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"}}'

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

curl https://api.blon.ai/v1/jobs/cmh2x0f6k0001qv8z9d4c1a7e \
  -H "Authorization: Bearer $BLON_API_KEY"

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

curl "https://api.blon.ai/v1/usage?timeframe=day" \
  -H "Authorization: Bearer $BLON_API_KEY"

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