> 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/generations/create-generation.md).

# POST /generations

Start an asynchronous generation from text. Use this endpoint when Gamma should determine the layout from your input and generation settings.

## Create async generation

> Creates an asynchronous generation job. Provide either \`inputText\` for a single-page File, or a \`pages\` array to generate a multi-page File (optionally published as a Gamma site via \`publish\`). Returns a generation ID that can be used to poll for status.

```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":{"Generation":{"type":"object","properties":{"textMode":{"description":"How to interpret the input text","enum":["condense","generate","preserve"],"type":"string"},"pages":{"minItems":1,"maxItems":50,"description":"Generate multiple pages in a single File. When provided, takes precedence over the top-level per-page fields (`inputText`, `textMode`, `numCards`, `format`, `additionalInstructions`, `cardSplit`, `textOptions`, `imageOptions`). File-level options (theme, sharing, folders, card dimensions, export, publish) still apply to all pages. Up to 50 pages per request.","type":"array","items":{"$ref":"#/components/schemas/PageGeneration"}},"format":{"description":"Output format for the generated Gamma","enum":["document","presentation","social","webpage"],"type":"string"},"cardSplit":{"description":"How to split content across cards","enum":["auto","inputTextBreaks"],"type":"string"},"exportAs":{"description":"Export format for automatic export after generation","enum":["pdf","png","pptx"],"type":"string"},"inputText":{"type":"string","description":"The text content to generate from (topic, outline, or full content)","minLength":1,"maxLength":400000},"title":{"type":"string","description":"Custom title for the generated Gamma. If not provided, a title will be automatically generated from the content.","minLength":1,"maxLength":500},"additionalInstructions":{"type":"string","description":"Additional instructions for the AI","minLength":0,"maxLength":5000},"publish":{"type":"boolean","description":"If true, publishes the generated File as a Gamma site after all\npages succeed. Applies to multi-page (`pages`) requests."},"numCards":{"type":"number","description":"Target number of cards/slides to generate","minimum":1},"themeId":{"type":"string","description":"Theme ID to apply (from /themes endpoint)"},"textOptions":{"description":"Text generation options","allOf":[{"$ref":"#/components/schemas/TextOptions"}]},"imageOptions":{"description":"Image generation and selection options","allOf":[{"$ref":"#/components/schemas/ImageOptions"}]},"cardOptions":{"description":"Card dimensions and layout options","allOf":[{"$ref":"#/components/schemas/CardOptions"}]},"sharingOptions":{"description":"Sharing and permissions options","allOf":[{"$ref":"#/components/schemas/SharingOptions"}]},"folderIds":{"description":"Folder to place the generated Gamma in. Accepts at most 1 folder ID.","maxItems":1,"type":"array","items":{"type":"string"}}}},"PageGeneration":{"type":"object","properties":{"textMode":{"description":"How to interpret this page's input text","enum":["condense","generate","preserve"],"type":"string"},"format":{"description":"Output format for this page","enum":["document","presentation","social","webpage"],"type":"string"},"cardSplit":{"description":"How to split content across cards for this page","enum":["auto","inputTextBreaks"],"type":"string"},"title":{"type":"string","description":"Custom title for this page. If not provided, a title will be\nautomatically generated from the content.","minLength":1,"maxLength":500},"inputText":{"type":"string","description":"The text content to generate from (topic, outline, or full content)","minLength":1,"maxLength":400000},"additionalInstructions":{"type":"string","description":"Additional instructions for the AI for this page","minLength":0,"maxLength":5000},"numCards":{"type":"number","description":"Target number of cards for this page","minimum":1},"path":{"type":"string","description":"URL slug for this page within the published site. When omitted,\nGamma derives a slug from the generated title and disambiguates\ncollisions. Honored for additional pages (pages 2..N); the first\npage is the File's main page and its path is implicit.","minLength":1,"maxLength":500},"textOptions":{"description":"Text generation options for this page","allOf":[{"$ref":"#/components/schemas/TextOptions"}]},"imageOptions":{"description":"Image generation and selection options for this page","allOf":[{"$ref":"#/components/schemas/ImageOptions"}]}},"required":["inputText"]},"TextOptions":{"type":"object","properties":{"amount":{"description":"Controls the amount of text generated per card","enum":["brief","detailed","extensive","medium"],"type":"string"},"language":{"description":"Language code for the generated content","enum":["af","ar","ar-sa","bg","bn","bs","ca","cs","cy","da","de","el","en","en-gb","en-in","es","es-419","es-es","es-mx","et","fa","fi","fr","gu","ha","he","hi","hr","hu","id","is","it","ja","ja-da","kk","kn","ko","lt","lv","mk","ml","mr","ms","nb","nl","pl","pt-br","pt-pt","ro","ru","sl","sq","sr","sv","sw","ta","te","th","tl","tr","uk","ur","uz","vi","yo","zh-cn","zh-tw"],"type":"string"},"tone":{"type":"string","description":"The tone or writing style for the generated text","minLength":0,"maxLength":500},"audience":{"type":"string","description":"The target audience for the content","minLength":0,"maxLength":500}}},"ImageOptions":{"type":"object","properties":{"model":{"description":"AI model to use for image generation","allOf":[{"$ref":"#/components/schemas/ImageModel"}]},"source":{"description":"Source for images: AI-generated or web search","enum":["aiGenerated","giphy","noImages","pexels","pictographic","placeholder","themeAccent","webAllImages","webFreeToUse","webFreeToUseCommercially"],"type":"string"},"style":{"type":"string","description":"Style description for AI-generated images","minLength":0,"maxLength":5000}}},"ImageModel":{"type":"string","enum":["dall-e-3","flux-1-pro","flux-1-quick","flux-1-ultra","flux-2-flex","flux-2-klein","flux-2-max","flux-2-pro","flux-kontext-fast","flux-kontext-max","flux-kontext-pro","gemini-2.5-flash-image","gemini-3-pro-image","gemini-3-pro-image-hd","gemini-3.1-flash-image","gemini-3.1-flash-image-hd","gemini-3.1-flash-image-mini","gpt-image-1-high","gpt-image-1-medium","gpt-image-1-mini-high","gpt-image-1-mini-low","gpt-image-1-mini-medium","gpt-image-2","gpt-image-2-hd","gpt-image-2-mini","ideogram-v3","ideogram-v3-quality","ideogram-v3-turbo","imagen-3-flash","imagen-3-pro","imagen-4-pro","imagen-4-ultra","leonardo-motion-2","leonardo-motion-2-fast","leonardo-phoenix","luma-photon-1","luma-photon-flash-1","luma-ray-2","luma-ray-2-flash","recraft-v3","recraft-v3-svg","recraft-v4","recraft-v4-pro","recraft-v4-svg","veo-3.1","veo-3.1-fast"],"description":"AI model to use for image generation"},"CardOptions":{"type":"object","properties":{"dimensions":{"description":"Card aspect ratio/dimensions","enum":["16x9","1x1","4x3","4x5","9x16","a4","fluid","letter","pageless"],"type":"string"},"headerFooter":{"description":"Header and footer configuration","allOf":[{"$ref":"#/components/schemas/HeaderFooter"}]}}},"HeaderFooter":{"type":"object","properties":{"topLeft":{"description":"Element in top-left position","allOf":[{"$ref":"#/components/schemas/HeaderFooterElement"}]},"topCenter":{"description":"Element in top-center position","allOf":[{"$ref":"#/components/schemas/HeaderFooterElement"}]},"topRight":{"description":"Element in top-right position","allOf":[{"$ref":"#/components/schemas/HeaderFooterElement"}]},"bottomLeft":{"description":"Element in bottom-left position","allOf":[{"$ref":"#/components/schemas/HeaderFooterElement"}]},"bottomCenter":{"description":"Element in bottom-center position","allOf":[{"$ref":"#/components/schemas/HeaderFooterElement"}]},"bottomRight":{"description":"Element in bottom-right position","allOf":[{"$ref":"#/components/schemas/HeaderFooterElement"}]},"hideFromFirstCard":{"type":"boolean","description":"Hide header/footer from the first card (title card)"},"hideFromLastCard":{"type":"boolean","description":"Hide header/footer from the last card"}}},"HeaderFooterElement":{"type":"object","properties":{"type":{"type":"string","description":"Type of element to display","enum":["cardNumber","image","text"]},"source":{"type":"string","description":"Image source type (required when type is \"image\")","enum":["custom","themeLogo"]},"src":{"type":"string","description":"Custom image URL (required when source is \"custom\")","format":"uri","minLength":1,"maxLength":2048},"value":{"type":"string","description":"Text content (required when type is \"text\")","minLength":1,"maxLength":500},"size":{"type":"string","description":"Size of the image element","enum":["lg","md","sm","xl"]}},"required":["type"]},"SharingOptions":{"type":"object","properties":{"workspaceAccess":{"description":"Default access level for workspace members","enum":["comment","edit","fullAccess","noAccess","view"],"type":"string"},"externalAccess":{"description":"Access level for external users (via shared link)","enum":["comment","edit","noAccess","view"],"type":"string"},"emailOptions":{"description":"Email sharing configuration","allOf":[{"$ref":"#/components/schemas/EmailOptions"}]}}},"EmailOptions":{"type":"object","properties":{"access":{"description":"Permission level for email recipients","enum":["comment","edit","fullAccess","view"],"type":"string"},"recipients":{"description":"Email addresses to share with","minItems":1,"type":"array","items":{"type":"string","format":"email"}}},"required":["recipients"]},"CreateGenerationResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier for the generation job"},"warnings":{"type":"string","description":"File-level warnings about the request (e.g., ignored sharing,\nfolder, or dimension options that apply to the whole gamma)."},"pageWarnings":{"description":"Page-level warnings, one entry per requested page (index-aligned\nwith the `pages` request array); `null` for a page with none. Each\nentry contains only that page's warnings.","type":"array","items":{"type":"string"}}},"required":["generationId"]}}},"paths":{"/v1.0/generations":{"post":{"description":"Creates an asynchronous generation job. Provide either `inputText` for a single-page File, or a `pages` array to generate a multi-page File (optionally published as a Gamma site via `publish`). Returns a generation ID that can be used to poll for status.","operationId":"createGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"responses":{"200":{"description":"Generation job created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGenerationResponse"}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Invalid or missing API key"},"402":{"description":"Insufficient credits"},"403":{"description":"Access denied or feature not available"}},"summary":"Create async generation","tags":["public-api"]}}}}
```

{% hint style="info" %}
For parameter guidance, see [Generate from text](/guides/generate-api-parameters-explained.md).
{% endhint %}

## Inspecting rate limit headers

Every response from the Gamma API includes rate limit headers (`x-ratelimit-remaining-burst`, `x-ratelimit-remaining`, `x-ratelimit-remaining-daily`). When testing with curl, add the `-i` flag to display these headers alongside the response body:

```bash
curl -i -X POST "https://public-api.gamma.app/v1.0/generations" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputText": "Create a presentation about renewable energy",
    "textMode": "generate"
  }'
```

Without `-i`, curl only shows the JSON body. In Python, JavaScript, or any HTTP client, these headers are accessible on the response object without any special flag.

See [Rate limit headers and adaptive polling](/guides/async-patterns-and-polling.md#rate-limit-headers-and-adaptive-polling) for how to use these headers to pace polling.

## Related

* [Generate from text](/guides/generate-api-parameters-explained.md) for parameter-by-parameter guidance
* [GET /generations/{id}](/generations/get-generation-status.md) for the polling step after creation
* [Async patterns and polling](/guides/async-patterns-and-polling.md) for the full polling workflow and rate limit guidance


---

# 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/generations/create-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.