# 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 from provided text input. 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":{"type":"string","description":"How to interpret the input text","enum":["generate","condense","preserve"]},"format":{"type":"string","description":"Output format for the generated Gamma","enum":["presentation","document","social","webpage"]},"cardSplit":{"type":"string","description":"How to split content across cards","enum":["inputTextBreaks","auto"]},"exportAs":{"type":"string","description":"Export format for automatic export after generation","enum":["pptx","pdf","png"]},"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","minLength":0,"maxLength":5000},"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 IDs to place the generated Gamma in","maxItems":10,"type":"array","items":{"type":"string"}}},"required":["inputText"]},"TextOptions":{"type":"object","properties":{"amount":{"type":"string","description":"Controls the amount of text generated per card","enum":["brief","medium","detailed","extensive"]},"language":{"type":"string","description":"Language code for the generated content","enum":["en","en-gb","en-in","es","es-es","es-mx","es-419","ca","fr","zh-cn","zh-tw","ko","ja","ja-da","pt-br","pt-pt","de","it","ru","pl","uk","ro","hu","cs","el","tr","ar","ar-sa","he","fa","nl","sv","da","nb","fi","id","vi","hi","gu","mr","te","bn","ta","ur","kn","ml","th","sr","hr","sq","bg","sl","bs","mk","sw","ha","yo","tl","ms","kk","uz","af","lv","lt","et","is","cy"]},"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":{"type":"string","description":"Source for images: AI-generated or web search","enum":["webAllImages","webFreeToUse","webFreeToUseCommercially","aiGenerated","pictographic","giphy","pexels","placeholder","noImages","themeAccent"]},"style":{"type":"string","description":"Style description for AI-generated images","minLength":0,"maxLength":5000}}},"ImageModel":{"type":"string","enum":["dall-e-3","imagen-3-flash","imagen-3-pro","imagen-4-pro","imagen-4-ultra","ideogram-v3","ideogram-v3-turbo","ideogram-v3-quality","flux-1-pro","flux-1-quick","flux-1-ultra","flux-kontext-pro","flux-kontext-max","flux-kontext-fast","leonardo-phoenix","recraft-v3","recraft-v3-svg","recraft-v4","recraft-v4-svg","recraft-v4-pro","luma-photon-1","luma-photon-flash-1","gpt-image-1-medium","gpt-image-1-high","gpt-image-1-mini-low","gpt-image-1-mini-medium","gpt-image-1-mini-high","gpt-image-2-mini","gpt-image-2","gpt-image-2-hd","gemini-2.5-flash-image","veo-3.1-fast","veo-3.1","luma-ray-2-flash","luma-ray-2","leonardo-motion-2-fast","leonardo-motion-2","gemini-3-pro-image","gemini-3-pro-image-hd","gemini-3.1-flash-image-mini","gemini-3.1-flash-image","gemini-3.1-flash-image-hd","flux-2-pro","flux-2-flex","flux-2-max","flux-2-klein"],"description":"AI model to use for image generation"},"CardOptions":{"type":"object","properties":{"dimensions":{"type":"string","description":"Card aspect ratio/dimensions","enum":["fluid","16x9","4x3","pageless","letter","a4","1x1","4x5","9x16"]},"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":"object","description":"Type of element to display"},"source":{"type":"object","description":"Image source type (required when type is \"image\")"},"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":"object","description":"Size of the image element"}},"required":["type"]},"SharingOptions":{"type":"object","properties":{"workspaceAccess":{"type":"string","description":"Default access level for workspace members","enum":["edit","comment","view","noAccess","fullAccess"]},"externalAccess":{"type":"string","description":"Access level for external users (via shared link)","enum":["edit","comment","view","noAccess"]},"emailOptions":{"description":"Email sharing configuration","allOf":[{"$ref":"#/components/schemas/EmailOptions"}]}}},"EmailOptions":{"type":"object","properties":{"access":{"type":"string","description":"Permission level for email recipients","enum":["edit","comment","view","fullAccess"]},"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":"Warnings about the request (e.g., ignored parameters)"}},"required":["generationId"]}}},"paths":{"/v1.0/generations":{"post":{"description":"Creates an asynchronous generation job from provided text input. 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"}}}},"201":{"description":"","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: 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:

```
GET https://developers.gamma.app/generations/create-generation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.