---
title: "generate an image with AI"
method: POST
path: "/api/images/generate"
tags: ["images"]
---

# generate an image with AI

`POST /api/images/generate`

## Request

- Base URL: `https://dev.to`
- URL: `https://dev.to/api/images/generate`
- Auth: one of:
  - API key in header `api-key`
  - HTTP bearer

Generate an image from a text prompt and get back a URL hosted by this Forem.

The image follows this Forem's cover image style and, unless `aspect_ratio` is given, is sized for its cover images. Use the URL in `body_markdown` or as an article's `main_image`, just like an uploaded image.

### Limits:
- `prompt` is required and may be up to 1000 characters.
- Rate limited per user to a configurable number of generations per configurable window (by default 3 per day). Every attempt counts, including failed ones. Exceeding it returns `429` with a `Retry-After` header. Forem admins can change both values, or set the limit to 0 to disable this endpoint.
- Returns `503` if AI image generation is not configured on this Forem.

## Request body

- object
  - `prompt` string, required: A description of the image to generate.
  - `aspect_ratio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9': Aspect ratio of the image. Defaults to this Forem's cover image shape.

## Response `201`

created

- ImageUrl: An image hosted by this Forem, usable in body_markdown or as an article's main_image
  - `url` string, url, required

## Other responses

- `401`: unauthorized
- `422`: unprocessable
- `429`: too many requests
- `503`: AI image generation unavailable

## Changes

- **2026-10-12** (v1) `7b762577c2a4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/forem/apis/forem-api-v1/changes/api/images/generate/post.md)

---

[API](https://skmtc.dev/forem/apis/forem-api-v1.md) - [All operations](https://skmtc.dev/forem/apis/forem-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/forem/apis/forem-api-v1/revisions/36f1cf80cf48?raw)