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 from provided text input. Returns a generation ID that can be used to poll for status.

Authorizations

api-key

X-API-KEYstringRequired

API key for authentication

Body

application/json

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: 400000Required

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

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: 10Optional

Folder IDs to place the generated Gamma in

Example: ["folder_abc"]

Responses

200

Generation job created successfully

application/json

generationIdstringRequired

Unique identifier for the generation job

Example: abc123xyz

warningsstringOptional

Warnings about the request (e.g., ignored parameters)

Example: Image model ignored when source is web

400

Invalid request parameters

401

Invalid or missing API key

402

Insufficient credits

403

Access denied or feature not available

post

/v1.0/generations

HTTPcURLJavaScriptPython

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: 1465

{
  "textMode": "outline",
  "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",
  "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"
}

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