# Explore the API

The Gamma API generates polished presentations, documents, websites, and social posts from text. Everything runs asynchronously: you create a generation, poll for status, and retrieve the result.

Use this page to decide which workflow fits your use case. When you need the exact request schema, field types, or response contract, see the individual endpoint reference pages.

### How it works

{% stepper %}
{% step %}
**Create a generation**

`POST /v1.0/generations` with your content and parameters. You get back a `generationId`.
{% endstep %}

{% step %}
**Poll for status**

`GET /v1.0/generations/{generationId}` every 5 seconds until `status` is `completed` or `failed`.
{% endstep %}

{% step %}
**Get your result**

The completed response includes `gammaUrl` (view it in Gamma) and `exportUrl` (download as PDF, PPTX, or PNG).
{% endstep %}
{% endstepper %}

See [Poll for results](https://developers.gamma.app/guides/async-patterns-and-polling) for full implementation examples in Python, JavaScript, and cURL.

### Quick reference

* Use `POST /v1.0/generations` when you want Gamma to create the layout from your prompt and parameters.
* Use `POST /v1.0/generations/from-template` when you already have a Gamma template and want repeated outputs in the same structure.
* Poll `GET /v1.0/generations/{generationId}` until `status` is `completed` or `failed`.
* Use `GET /v1.0/themes` and `GET /v1.0/folders` to look up IDs before generation.

### Two ways to generate

|                     | Generate API                                                                                               | Create from Template API                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**        | `POST /v1.0/generations`                                                                                   | `POST /v1.0/generations/from-template`                                                                                     |
| **When to use**     | Creating from scratch. Maximum flexibility — you control format, tone, audience, images, layout, and more. | Producing variations of a consistent layout. Design the template once in the Gamma app, then generate new content into it. |
| **Required fields** | `inputText` + `textMode`                                                                                   | `prompt` + `gammaId`                                                                                                       |
| **Key difference**  | AI determines the layout based on your parameters.                                                         | Layout stays fixed to your template. Only the content changes.                                                             |

Both endpoints support `themeId`, `exportAs`, `sharingOptions`, and `folderIds`. See the full parameter reference for each:

* [Generate API Parameters](https://developers.gamma.app/guides/generate-api-parameters-explained)
* [Create from Template Parameters](https://developers.gamma.app/guides/create-from-template-api-parameters-explained)

### Key parameters at a glance

| Parameter                  | What it controls                   | Example values                                                                                                              |
| -------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `format`                   | Output type                        | `presentation`, `document`, `webpage`, `social`                                                                             |
| `textMode`                 | How input text is interpreted      | `generate` (topic → content), `condense` (summarize), `preserve` (keep as-is)                                               |
| `themeId`                  | Brand theme (colors, fonts, logo)  | Get IDs from `GET /v1.0/themes`                                                                                             |
| `numCards`                 | Number of slides/sections          | `1`–`75` depending on plan                                                                                                  |
| `exportAs`                 | Auto-export on completion          | `pdf`, `pptx`, `png`                                                                                                        |
| `imageOptions.source`      | Where images come from             | `aiGenerated`, `webFreeToUseCommercially`, `noImages`                                                                       |
| `textOptions.tone`         | Writing style                      | Any string: `"professional"`, `"casual"`, `"academic"`                                                                      |
| `textOptions.audience`     | Who the content is for             | Any string: `"executives"`, `"new hires"`, `"students"`                                                                     |
| `cardOptions.headerFooter` | Logo, page numbers, text           | 6 positions per card — see [Header and Footer Formatting](https://developers.gamma.app/guides/header-and-footer-formatting) |
| `sharingOptions`           | Permissions on the generated gamma | Workspace, external link, and email access levels                                                                           |

### Supporting endpoints

| Endpoint            | Purpose                                                                                |
| ------------------- | -------------------------------------------------------------------------------------- |
| `GET /v1.0/themes`  | List available themes (standard + custom workspace themes). Use the `id` as `themeId`. |
| `GET /v1.0/folders` | List workspace folders. Use folder `id` values in `folderIds`.                         |

Both list endpoints use cursor-based pagination: check `hasMore`, pass `nextCursor` as the `after` query param.

### Authentication

All requests require an API key in the `X-API-KEY` header. Generate your key from [Account Settings > API Keys](https://gamma.app/settings/api-keys).

```bash
curl https://public-api.gamma.app/v1.0/themes \
  -H "X-API-KEY: $GAMMA_API_KEY"
```

API access requires a Pro, Ultra, Teams, or Business plan. See [Access and Pricing](https://developers.gamma.app/get-started/access-and-pricing) for credit costs and plan details.

{% hint style="info" %}
**Not a developer?** You can also use Gamma through [connectors and integrations](https://developers.gamma.app/connectors/connectors-and-integrations) — no code required.
{% endhint %}

### Related

* [Generate from text](https://developers.gamma.app/guides/generate-api-parameters-explained) for a parameter-by-parameter walkthrough of `POST /v1.0/generations`
* [Generate from a template](https://developers.gamma.app/guides/create-from-template-api-parameters-explained) for the fixed-layout workflow
* [Poll for results](https://developers.gamma.app/guides/async-patterns-and-polling) for complete polling implementations