POST /generations

Generate a presentation, document, website, or social post from text.

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

Create async generation

post

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.

Authorizations

X-API-KEYstringRequired

API key for authentication

Body

textModestring · enumOptional

How to interpret the input text

Example: outlinePossible values:

formatstring · enumOptional

Output format for the generated Gamma

Example: presentationPossible values:

cardSplitstring · enumOptional

How to split content across cards

Example: autoPossible values:

exportAsstring · enumOptional

Export format for automatic export after generation

Example: pdfPossible values:

inputTextstring · min: 1 · max: 400000Optional

The text content to generate from (topic, outline, or full content)

Example: Quarterly sales report for Q3 2024

titlestring · min: 1 · max: 500Optional

Custom title for the generated Gamma. If not provided, a title will be automatically generated from the content.

Example: Q3 2024 Sales Report

additionalInstructionsstring · max: 5000Optional

Additional instructions for the AI

Example: Focus on year-over-year growth metrics

publishbooleanOptional

If true, publishes the generated File as a Gamma site after all pages succeed. Applies to multi-page (pages) requests.

Example: true

numCardsnumber · min: 1Optional

Target number of cards/slides to generate

Example: 10

themeIdstringOptional

Theme ID to apply (from /themes endpoint)

Example: theme_abc123

folderIdsstring[] · max: 1Optional

Folder to place the generated Gamma in. Accepts at most 1 folder ID.

Example: ["folder_abc"]

Responses

200

Generation job created successfully

application/json

generationIdstringRequired

Unique identifier for the generation job

Example: abc123xyz

warningsstringOptional

File-level warnings about the request (e.g., ignored sharing, folder, or dimension options that apply to the whole gamma).

Example: Image model ignored when source is web

pageWarningsstring[]Optional

Page-level warnings, one entry per requested page (index-aligned with the pages request array); null for a page with none. Each entry contains only that page's warnings.

400

Invalid request parameters

401

Invalid or missing API key

402

Insufficient credits

403

Access denied or feature not available

post/v1.0/generations

POST /v1.0/generations HTTP/1.1
Host: public-api.gamma.app
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1565

{
  "textMode": "outline",
  "pages": [
    {
      "inputText": "Overview",
      "numCards": 5
    },
    {
      "inputText": "Pricing",
      "numCards": 3
    }
  ],
  "format": "presentation",
  "cardSplit": "auto",
  "exportAs": "pdf",
  "inputText": "Quarterly sales report for Q3 2024",
  "title": "Q3 2024 Sales Report",
  "additionalInstructions": "Focus on year-over-year growth metrics",
  "publish": true,
  "numCards": 10,
  "themeId": "theme_abc123",
  "textOptions": {
    "amount": "auto",
    "language": "en",
    "tone": "professional",
    "audience": "marketing executives"
  },
  "imageOptions": {
    "model": "flux-2-pro",
    "source": "aiGenerated",
    "style": "photorealistic, professional"
  },
  "cardOptions": {
    "dimensions": "16x9",
    "headerFooter": {
      "topLeft": {
        "type": "text",
        "source": "themeLogo",
        "src": "https://example.com/logo.png",
        "value": "Confidential",
        "size": "md"
      },
      "topCenter": {
        "type": "text",
        "source": "themeLogo",
        "src": "https://example.com/logo.png",
        "value": "Confidential",
        "size": "md"
      },
      "topRight": {
        "type": "text",
        "source": "themeLogo",
        "src": "https://example.com/logo.png",
        "value": "Confidential",
        "size": "md"
      },
      "bottomLeft": {
        "type": "text",
        "source": "themeLogo",
        "src": "https://example.com/logo.png",
        "value": "Confidential",
        "size": "md"
      },
      "bottomCenter": {
        "type": "text",
        "source": "themeLogo",
        "src": "https://example.com/logo.png",
        "value": "Confidential",
        "size": "md"
      },
      "bottomRight": {
        "type": "text",
        "source": "themeLogo",
        "src": "https://example.com/logo.png",
        "value": "Confidential",
        "size": "md"
      },
      "hideFromFirstCard": true,
      "hideFromLastCard": false
    }
  },
  "sharingOptions": {
    "workspaceAccess": "view",
    "externalAccess": "none",
    "emailOptions": {
      "access": "view",
      "recipients": [
        "[e-mail]"
      ]
    }
  },
  "folderIds": [
    "folder_abc"
  ]
}

{
  "generationId": "abc123xyz",
  "warnings": "Image model ignored when source is web",
  "pageWarnings": [
    "text"
  ]
}

For parameter guidance, see Generate from text.

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:

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 for how to use these headers to pace polling.

Related

• Generate from text for parameter-by-parameter guidance
• GET /generations/{id} for the polling step after creation
• Async patterns and polling for the full polling workflow and rate limit guidance