Getting started

Quickstart

From zero to your first image in three steps: grab a key, fire off a generation, and fetch the result URL.

1. Grab a key

Sign in to the app at Account → Apps & API and create a key. It's shown once, in the format ck_live_… — keep it secret. The API is in closed beta: your account needs to be enabled (active plan). Store the key in an environment variable:

export CK=ck_live_xxxxxxxxxxxxxxxxxxxxxxxx

2. Fire off a generation

Every generation is a POST /generations. Send the model (a slug from Models) and the prompt. The response comes back immediately with status: "processing" — the job runs in the background.

curl -X POST https://caranguejo.art/api/v1/dev/generations \
  -H "Authorization: Bearer $CK" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "um caranguejo numa praia neon, cinematográfico",
    "params": { "quality": "high", "resolution": "2K", "size": "3:2" }
  }'

Response (job accepted, 201):

{
  "data": {
    "id": "9f0c1a7e-…",
    "object": "generation",
    "status": "processing",
    "model": "gpt-image-2"
  }
}

3. Track it until it completes

Poll GET /generations/:id until status turns to completed (or failed). In production, prefer a webhook over polling.

curl https://caranguejo.art/api/v1/dev/generations/9f0c1a7e-… \
  -H "Authorization: Bearer $CK"

{
  "data": {
    "id": "9f0c1a7e-…",
    "status": "completed",
    "credits_charged": 40,
    "output": {
      "assets": [{ "url": "https://media.caranguejo.art/…/out.png", "type": "image" }],
      "images": [{ "url": "https://media.caranguejo.art/…/out.png" }]
    }
  }

4. Use the result

The URL in output.assets[].url is permanent and public (media.caranguejo.art) — no expiration, no signature. Download it or serve it directly. The job's actual cost comes back in credits_charged.