Generate image

POST /ai/generate-image

Generate an AI image from a text prompt. The image is stored in your media library and can be attached to posts via media_ids.

Requires the ai scope on your API key.

Available models:

Model	Credits	Speed	Best for
`nano-banana-pro`	15	~5s	Best overall quality
`ideogram-v2`	8	~5s	Text in images
`gemini-3-pro`	5	~8s	Smart/contextual
`flux-schnell`	1	~2s	Fast drafts

Request Body Schema

POST /ai/generate-image — Content-Type: application/json

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the image to generate (max 2000 chars)
`aspect_ratio`	string	No	Output image aspect ratio. Default `1:1`.
`model`	string	No	AI model to use. Default `nano-banana-pro`.

Supported aspect ratios

1:1, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4

Request Example

{
  "prompt": "A professional photo of a modern office workspace with natural lighting",
  "aspect_ratio": "16:9",
  "model": "nano-banana-pro"
}

Response Examples

201 — Image generated successfully

{
  "data": {
    "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "model": "nano-banana-pro",
    "aspect_ratio": "16:9",
    "credits_used": 15,
    "credits_remaining": 485,
    "message": "Image generated successfully. Attach it to a post using media_ids."
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
`media_id`	string (UUID)	Use this ID to attach the image to a post via `media_ids`
`model`	string	Model that was used for generation
`aspect_ratio`	string	Aspect ratio of the generated image
`credits_used`	integer	Credits consumed by this generation
`credits_remaining`	integer	Credits remaining after this generation
`message`	string	Human-readable success message

400 — Invalid prompt or parameters

{
  "data": null,
  "error": {
    "message": "Invalid aspect ratio. Must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4",
    "code": "validation_error"
  },
  "meta": {
    "request_id": "e5f6g7h8",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

402 — Insufficient credits

{
  "data": null,
  "error": {
    "message": "Not enough credits. This model costs 15 credits but you have 3 available.",
    "code": "insufficient_credits",
    "details": {
      "credits_required": 15,
      "credits_available": 3,
      "model": "nano-banana-pro"
    }
  },
  "meta": {
    "request_id": "i9j0k1l2",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Request

Responses

Image generated successfully

Generate image

/ai/generate-image

Request Body Schema​

Supported aspect ratios​

Request Example​

Response Examples​

201 — Image generated successfully​

Response fields​

400 — Invalid prompt or parameters​

402 — Insufficient credits​

Request​

Responses​