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.

Copy media_ids straight into your post

The response contains a media_ids array (plural, single-element) — copy it directly into the media_ids field of POST /v1/posts with no transformation. The next_step field contains a human-readable instruction.

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",
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "type": "image",
    "width": 1920,
    "height": 1080,
    "aspect_ratio": "16:9",
    "ai": {
      "model": "nano-banana-pro",
      "prompt": "A professional photo of a modern office workspace with natural lighting"
    },
    "credits_used": 15,
    "credits_remaining": 485,
    "created_at": "2026-04-10T12:00:00.000Z",
    "next_step": "Image generated. Attach it to a post by passing \"media_ids\": [\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"] to POST /v1/posts."
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
`media_id`	string (UUID)	The single UUID for the generated image
`media_ids`	string[] (UUID)	Convenience single-element array — copy straight into `POST /v1/posts`
`type`	string	Always `"image"` for this endpoint
`width`	integer	Image pixel width
`height`	integer	Image pixel height
`aspect_ratio`	string	Aspect ratio of the generated image (matches request)
`ai.model`	string	AI model used for generation
`ai.prompt`	string	Prompt supplied in the request (echoed for round-trip convenience)
`credits_used`	integer	Credits consumed by this generation
`credits_remaining`	integer	Credits remaining in your workspace after this generation
`created_at`	string (ISO 8601)	UTC timestamp when the media record was created
`next_step`	string	Human-readable instruction for attaching the image to a post

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​