# 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. See the \[Quickstart]\(/) for a complete example.

```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":{"inputText":{"type":"string","description":"Input text for generation (topic, outline, or content). See [Generate API Parameters](/overview/generate-api-parameters-explained) for input strategies.","minLength":1,"maxLength":400000},"additionalInstructions":{"type":"string","description":"Additional context or instructions for AI","minLength":0,"maxLength":5000},"textMode":{"$ref":"#/components/schemas/TextMode"},"format":{"$ref":"#/components/schemas/DocFormat"},"numCards":{"type":"number","description":"Target number of cards to generate. Limits vary by plan — see [Access and Pricing](/overview/access-and-pricing).","minimum":1},"cardSplit":{"$ref":"#/components/schemas/CardSplit"},"themeId":{"type":"string","description":"Theme ID to apply. Get IDs from [Themes and Folders APIs](/overview/list-themes-and-list-folders-apis-explained)."},"textOptions":{"description":"Text generation options. See [Generate API Parameters](/overview/generate-api-parameters-explained) for tone, audience, and language guidance.","allOf":[{"$ref":"#/components/schemas/TextOptions"}]},"imageOptions":{"description":"Image generation and selection options. See [Image model accepted values](/accepted-values/image-model-accepted-values) for all models with plan requirements and credits.","allOf":[{"$ref":"#/components/schemas/ImageOptions"}]},"cardOptions":{"description":"Card dimensions and layout options. See [Header and Footer Formatting](/overview/header-and-footer-formatting) for layout examples.","allOf":[{"$ref":"#/components/schemas/CardOptions"}]},"sharingOptions":{"description":"Sharing and permissions options. See [Generate API Parameters](/overview/generate-api-parameters-explained) for permission examples.","allOf":[{"$ref":"#/components/schemas/SharingOptions"}]},"folderIds":{"description":"Folders to add the generated Gamma to. Get IDs from [Themes and Folders APIs](/overview/list-themes-and-list-folders-apis-explained).","maxItems":10,"type":"array","items":{"type":"string"}},"exportAs":{"description":"Auto-export format. See [Async Patterns and Polling](/overview/async-patterns-and-polling) for downloading exports.","$ref":"#/components/schemas/ExportFormat"}},"required":["inputText","textMode"]},"TextMode":{"type":"string","description":"How to interpret the input text","enum":["generate","condense","preserve"]},"DocFormat":{"type":"string","description":"Output format","enum":["presentation","document","social","webpage"]},"CardSplit":{"type":"string","description":"Content splitting strategy across cards","enum":["inputTextBreaks","auto"]},"TextOptions":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/TextAmount"},"tone":{"type":"string","description":"The tone or writing style (e.g., professional, casual, academic)","minLength":0,"maxLength":500},"audience":{"type":"string","description":"Target audience description for tailored content","minLength":0,"maxLength":500},"language":{"$ref":"#/components/schemas/AILocale"}}},"TextAmount":{"type":"string","description":"Controls the amount of text generated per card","enum":["brief","medium","detailed","extensive"]},"AILocale":{"type":"string","description":"ISO language code for content generation","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"]},"ImageOptions":{"type":"object","properties":{"model":{"type":"string","description":"AI model for image generation. Available models depend on your plan. See [Image model accepted values](/accepted-values/image-model-accepted-values) for all models with plan requirements and credits.","enum":["dall-e-3","imagen-3-flash","imagen-3-pro","imagen-4-fast","imagen-4-pro","imagen-4-ultra","playground-3","ideogram-v2","ideogram-v2-turbo","ideogram-v2a","ideogram-v2a-turbo","ideogram-v3","ideogram-v3-turbo","ideogram-v3-quality","ideogram-v3-flash","flux-1-schnell","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-low","gpt-image-1-medium","gpt-image-1-high","gpt-image-1-mini-low","gpt-image-1-mini-medium","gpt-image-1-mini-high","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"]},"style":{"type":"string","description":"Style description for AI-generated images. See [Image URL Best Practices](/overview/image-url-best-practices).","minLength":0,"maxLength":500},"source":{"$ref":"#/components/schemas/ImageSource"}}},"ImageSource":{"type":"string","description":"Source for card images","enum":["webAllImages","webFreeToUse","webFreeToUseCommercially","aiGenerated","pictographic","giphy","pexels","placeholder","noImages","themeAccent"]},"CardOptions":{"type":"object","properties":{"dimensions":{"$ref":"#/components/schemas/CardDimensions"},"headerFooter":{"description":"Header and footer configuration. See [Header and Footer Formatting](/overview/header-and-footer-formatting) for layout examples.","allOf":[{"$ref":"#/components/schemas/HeaderFooter"}]}}},"CardDimensions":{"type":"string","description":"Card dimensions/aspect ratio","enum":["fluid","16x9","4x3","pageless","letter","a4","1x1","4x5","9x16"]},"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 first card"},"hideFromLastCard":{"type":"boolean","description":"Hide header/footer from last card"}}},"HeaderFooterElement":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/HeaderFooterElementType"},"source":{"type":"string","description":"Source for the image element","enum":["themeLogo","custom"]},"src":{"type":"string","description":"HTTPS URL for custom image","minLength":1,"maxLength":2048},"value":{"type":"string","description":"Text content to display","minLength":1,"maxLength":500},"size":{"type":"string","description":"Size of the image element","enum":["sm","md","lg","xl"]}},"required":["type"]},"HeaderFooterElementType":{"type":"string","description":"Type of element to display","enum":["cardNumber","image","text"]},"SharingOptions":{"type":"object","properties":{"workspaceAccess":{"$ref":"#/components/schemas/WorkspacePermission"},"externalAccess":{"$ref":"#/components/schemas/ExternalPermission"},"emailOptions":{"description":"Email sharing configuration","allOf":[{"$ref":"#/components/schemas/EmailOptions"}]}}},"WorkspacePermission":{"type":"string","description":"Access level for workspace members","enum":["edit","comment","view","noAccess","fullAccess"]},"ExternalPermission":{"type":"string","description":"Access level for external users via shared link","enum":["edit","comment","view","noAccess"]},"EmailOptions":{"type":"object","properties":{"recipients":{"description":"List of email addresses to share with","type":"array","items":{"type":"string"}},"access":{"$ref":"#/components/schemas/EmailPermission"}},"required":["recipients","access"]},"EmailPermission":{"type":"string","description":"Permission level for email recipients","enum":["edit","comment","view","fullAccess"]},"ExportFormat":{"type":"string","description":"Auto-export format after generation completes","enum":["pptx","pdf","png"]},"CreateGenerationResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique generation job identifier for status polling"},"warnings":{"type":"string","description":"Warnings about ignored or adjusted request parameters"}},"required":["generationId"]}}},"paths":{"/v1.0/generations":{"post":{"operationId":"createGeneration","summary":"Create async generation","description":"Creates an asynchronous generation job from provided text input. Returns a generation ID that can be used to poll for status. See the [Quickstart](/) for a complete example.","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"}},"tags":["public-api"]}}}}
```

{% hint style="info" %}
For parameter guidance, see [Generate from text](https://developers.gamma.app/guides/generate-api-parameters-explained).
{% 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.

For a full breakdown of the rate limit headers and how to use them for adaptive polling, see [Rate limit headers and adaptive polling](https://developers.gamma.app/guides/async-patterns-and-polling#rate-limit-headers-and-adaptive-polling).

## Related

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