Turn images into public URLs.

Convert an image (multipart)

Upload a binary file. The file field is required.

cURL

curl -X POST http://localhost/api/v1/images \
  -H "Authorization: Bearer sk_live_xxxxxxxxx" \
  -F "file=@/path/to/image.png"Copy

Response 200

{
  "success": true,
  "data": {
    "id": 42,
    "url": "http://localhost/i/ab/cd/key.png",
    "mime_type": "image/png",
    "size": 12345,
    "created_at": "2026-09-24T08:00:00"
  }
}

Convert a Base64 image

Send a JSON body with image set to a raw Base64 string or a data:image/...;base64,... URI.

cURL

curl -X POST http://localhost/api/v1/images \
  -H "Authorization: Bearer sk_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"image": "data:image/png;base64,iVBORw0KGgo..."}'Copy

Response 200

{
  "success": true,
  "data": {
    "id": 43,
    "url": "http://localhost/i/ab/cd/key.png",
    "mime_type": "image/png",
    "size": 69,
    "created_at": "2026-09-24T08:00:00"
  }
}

Generate an image from a prompt (AI)

Send a text prompt to the AI provider. Returns a public URL on success. Costs 5 credits per request. Rate-limited to 10 requests / 10 min / IP. Anonymous (no auth) is rejected with 401 UNAUTHORIZED.

Allowed fields

Only these four fields are accepted. Anything else (e.g. model, n, background, image_detail) returns 422 VALIDATION_ERROR — those are server-controlled and always read from the configs table.

• prompt — required, 1–2000 chars.
• size — optional. One of 1024x1024, 1024x1536, 1536x1024, auto.
• quality — optional. One of low, medium, high.
• output_format — optional, default png. One of png, jpeg, webp. The stored file always has the matching extension (.png, .jpg, .webp) — bytes are re-encoded to match.

cURL

curl -X POST http://localhost/api/v1/ai/generations \
  -H "Authorization: Bearer sk_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cute cat wearing a tiny astronaut helmet, watercolor style",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png"
  }'Copy

Response 200

{
  "success": true,
  "data": {
    "id": 4242,
    "url": "http://localhost/i/ab/cd/key.png",
    "storage_key": "key",
    "mime_type": "image/png",
    "size": 184320,
    "created_at": "2026-09-26T03:14:15",
    "expires_at": "2026-10-26T03:14:15",
    "credits_remaining": 95
  }
}

Server-controlled (not accepted from client)

• model — default ag/gemini-3.1-flash-image (configurable via ai_image.default_model).
• n — fixed at 1. One request = one image.
• background / image_detail — fixed to provider defaults.

Notes

• On provider error / timeout / content-policy block, the credit is refunded automatically.
• Generated images are stored with images.source = 5 (ai_generated) and counted in the AI generations tile of the Usage tab.
• Endpoint runs on the same auth + storage pipeline as POST /api/v1/images.