---
title: "Generate images"
method: POST
path: "/image"
tags: ["Images"]
---

# Generate images

`POST /image`

## Request

- Base URL: `https://api.wondercraft.ai/v1`
- URL: `https://api.wondercraft.ai/v1/image`
- Auth: API key in header `X-API-KEY`
- TypeScript: <https://skmtc.dev/wondercraft/apis/wondercraft-public-api/docs/image/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts a background job that generates images from a prompt, optionally editing or combining
reference images. The response contains a `job_id` to poll with `GET /image/{job_id}`, and the
credits the job will be charged. Requires a valid `X-API-KEY` header.

Throws:
- 400 if the model, resolution or aspect ratio is not supported, the model does not accept
  reference images, or the prompt references images the request does not carry
- 402 if the workspace does not have enough credits, or the model is not available on its plan
- 404 if a reference image does not exist or is not accessible
- 422 if the request body is invalid

## Request body

- GenerateImageApiRequest
  - `prompt` string, required: What to generate. Refer to references as `@Image 1`, …
  - `model_id` string, required: A model `id` from `GET /image/models`
  - `resolution` '480p' | '720p' | '1080p' | '2k' | '4k': Output resolution shared by the image and video APIs; each model lists the values it supports.
  - `aspect_ratio` '16:9' | '9:16' | '1:1'
  - `number_of_images` integer: How many images to generate in this job
  - `reference_image_ids` string[]: Images from `POST /image/upload` or earlier image jobs, in prompt order. The first is the image being edited; the rest are extra references.

## Response `200`

Successful Response

- CreateImageJobResponse
  - `job_id` string, uuid, required: Poll `GET /image/{job_id}` with this ID
  - `estimated_credits` number, required: Credits this job will be charged once the images are ready

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `200f24d7f14b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wondercraft/apis/wondercraft-public-api/changes/image/post.md)

---

[API](https://skmtc.dev/wondercraft/apis/wondercraft-public-api.md) - [All operations](https://skmtc.dev/wondercraft/apis/wondercraft-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wondercraft/apis/wondercraft-public-api/revisions/200f24d7f14b?raw)