> For the complete documentation index, see [llms.txt](https://developers.gamma.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gamma.app/images/create-image-generation.md).

# POST /images

Start an asynchronous image generation from a text prompt. Returns an `imageGenerationId` to poll for the image URL and metadata.

## Create async image generation

> Creates an asynchronous image generation job that produces one standalone on-brand image. Returns an image generation ID that can be used to poll for status. If \`themeId\` is provided but does not exist or is not accessible to your workspace, the request fails with 400.

```json
{"openapi":"3.0.0","info":{"title":"Gamma Public API","version":"1.0"},"tags":[{"name":"public-api","description":"Public API endpoints for external integrations"}],"servers":[{"url":"https://public-api.gamma.app","description":"Production"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication"}},"schemas":{"CreateImageGeneration":{"type":"object","properties":{"type":{"description":"Visual style of the generated images. Defaults to \"illustration\".\nSkipped when referenceImages are present — references take precedence\nand style comes from the prompt.","enum":["abstract","illustration","photo","scene"],"type":"string","default":"illustration"},"sizePreset":{"description":"Output size preset (sets the aspect ratio; exact pixel dimensions are\nmodel-determined). Defaults to \"social-square\" (1:1).","enum":["banner","slide","social-portrait","social-square","story"],"type":"string","default":"social-square"},"referenceImages":{"description":"Reference images with subject semantics (\"put this character or product\nin the scene\"). Maximum 4. When present, they take precedence over `type`\nand `themeId`.","maxItems":4,"type":"array","items":{"$ref":"#/components/schemas/ReferenceImage"}},"prompt":{"type":"string","description":"Description of the image to generate. Background treatments (\"on white\",\n\"contained in a circle\") go here.","maxLength":5000,"pattern":"\\S"},"themeId":{"type":"string","description":"Theme to brand the images with. Defaults to the workspace default theme.\nApplied for all types except `\"scene\"`, whose curated style ignores theme\ncolors (a `theme_ignored_for_type` warning is returned if you supply\n`themeId` for `scene`). Also ignored when referenceImages are present —\nreferences drive the look."}},"required":["prompt"]},"ReferenceImage":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS URL of the reference image. The server fetches, validates, and\nrehosts the image before generation.","format":"uri","pattern":"^https://"},"role":{"type":"string","description":"How the reference influences generation. `subject` places the pictured\ncharacter or product into the generated scene.","enum":["subject"]}},"required":["url"]},"CreateImageGenerationResponse":{"type":"object","properties":{"imageGenerationId":{"type":"string","description":"Unique identifier for the image generation job. Poll\n`GET /v1.0/images/{id}` with this id until status is \"completed\" or\n\"failed\"."},"warnings":{"description":"Warnings known at request time (e.g. a skipped style or theme)","type":"array","items":{"$ref":"#/components/schemas/ImageGenerationWarning"}}},"required":["imageGenerationId"]},"ImageGenerationWarning":{"type":"object","properties":{"code":{"description":"Machine-readable warning code","enum":["curated_style_skipped_for_references","no_brand_theme_applied","theme_ignored_for_type","theme_skipped_for_references"],"type":"string"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["code","message"]}}},"paths":{"/v1.0/images":{"post":{"description":"Creates an asynchronous image generation job that produces one standalone on-brand image. Returns an image generation ID that can be used to poll for status. If `themeId` is provided but does not exist or is not accessible to your workspace, the request fails with 400.","operationId":"createImageGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateImageGeneration"}}}},"responses":{"200":{"description":"Image generation job created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateImageGenerationResponse"}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Insufficient credits"},"403":{"description":"Access denied or feature not available"},"404":{"description":"Not found"}},"summary":"Create async image generation","tags":["public-api"]}}}}
```

{% hint style="info" %}
Poll [GET /images/{id}](/images/get-image-generation-status.md) with the returned `imageGenerationId` until `status` is `completed` or `failed`. If `themeId` does not exist or is not accessible to your workspace, the request fails with `400`.
{% endhint %}

## Related

* [GET /images/{id}](/images/get-image-generation-status.md) to poll for the image URL and `savedMediaId`
* [Poll for results](/guides/async-patterns-and-polling.md) for polling patterns and rate limit guidance
* [Warnings](/reference/warnings.md) for image-generation warning codes returned in the response


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.gamma.app/images/create-image-generation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.