API Reference

All endpoints accept and return JSON. Base path: /api/v1.

Authentication

Every request requires a bearer token:

Authorization: Bearer aig_xxx

Your key is shown on the API Key page after sign-in. Successful calls deduct one token from your account balance.

POST /api/v1/connection

Returns the current state of your account. Does not consume a token.

{
  "account_id": "uuid",
  "account_name": "...",
  "tokens": 50,
  "total_tokens_used": 0,
  "active": true
}

POST /api/v1/generate

Generates an artwork description JSON. Request:

{ "input_text": "Title: ... Artist: ...", "base64_of_image": "..." }

Response (FAF prompt profile):

{
  "title": "...",
  "intro": "...",
  "description": "...",
  "artist_bio": "...",
  "image_desc": "...",
  "meta_desc": "...",
  "meta_title": "...",
  "keywords": ["..."],
  "colours": ["..."],
  "image_prompt": "..."
}

POST /api/v1/generate-image

Creates an in-room mockup PNG using the artwork image and a prompt.

{ "input_text": "A bright modern living room...", "base64_of_image": "..." }

{ "image_base64": "iVBORw0KG...", "mime_type": "image/png" }

POST /api/v1/generate-artist-bio

Writes an artist bio JSON.

{ "artist": "Jane Doe", "current_bio": "" }

{
  "intro": "...",
  "short_desc": "...",
  "artist_bio": "...",
  "keywords": ["..."],
  "meta_desc": "...",
  "meta_title": "...",
  "key_facts": [{ "title": "...", "fact": "..." }]
}

Errors

401 — missing or invalid API key
402 — out of tokens (top up to continue)
403 — account suspended
400 — invalid request body
500/502 — upstream AI failure (logged on your Logs page)