Quick start

1. Create a key

Account → Developer Center → API Keys → Create API key. Give it a name, tick the scopes, pick an expiry.

For a first integration tick at least generate:write (generate) and assets:read (download images).

The key starts with sk_ and is shown only once. If you lose it, revoke it and create a new one.

2. Authentication

Every endpoint authenticates with a request header:

Authorization: Bearer sk_your_key

3. Generate an image

curl -X POST https://photopurr.com/api/v1/generate \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "White-background T-shirt hero shot, model facing front, soft lighting",
    "model": "nano-banana-2",
    "ratio": "3:4",
    "n": 1
  }'

Successful response:

{
  "ok": true,
  "turn_id": "t_xxxxxxxxxx",
  "session_id": "s_xxxxxxxxxx",
  "credits_charged": 16,
  "duration_ms": 18320,
  "warnings": [],
  "images": [
    {
      "id": "img_xxxxxxxx",
      "filename": "xxxxxxxx.jpg",
      "url": "/api/file/xxxxxxxx.jpg",
      "width": 1536,
      "height": 2048
    }
  ]
}

Full parameters, model capabilities and billing rules are in the API reference.

4. Download the image

images[].url is a relative path; request it with the same key. The endpoint answers with a 302 to a direct link valid for one hour, so follow redirects. Generated images are JPEG with a .jpg extension; only an image that actually uses transparency is a .png. The extension always matches the content, so keep the one in filename when you save:

curl -L https://photopurr.com/api/file/xxxxxxxx.jpg \
  -H "Authorization: Bearer sk_your_key" \
  -o result.jpg

Thumbnails, download parameters and retention are on the image download page.

5. Handle errors

On error the HTTP status is not 2xx and the body is:

{
  "error": {
    "code": "insufficient_credits",
    "message": "积分不足：需要 16，当前 3。请联系 … 充值。",
    "request_id": "req_xxxxxxxxxxxxxxxxxxxx"
  }
}

Branch on code, never on message: messages are in Chinese and may change. The full list is under error format.