For the complete documentation index, see llms.txt. This page is also available as Markdown.

POST /agent/generations

Start an asynchronous Gamma agent generation from a natural-language prompt.

Start a Gamma 5 agent generation from a prompt. This is the recommended endpoint for new presentations, documents, and social posts, and it also covers template-based generation through templateId; webpages and multi-page gammas are Classic-only (POST /generations). Returns a gen_-prefixed generationId to poll with GET /agent/generations/{generationId}, whose completed or failed response reports the credits charged (credits.deducted) and your remaining balance (credits.remaining) when those lookups succeed.

Create agent generation

post

Creates an asynchronous generation job run by the Gamma agent. prompt is the only required field. Guidance fields (numCards, additionalInstructions) are soft targets; numCards must not exceed the card maximum for the workspace plan. To work from your own files, such as a presentation to import, store each with POST /v1.0/uploads and list them in files. A folderId or sharingOptions setting that a workspace admin restricts is ignored and reported in warnings. Returns a gen_-prefixed generation ID to poll with GET /v1.0/agent/generations/{generationId}.

Authorizations
X-API-KEYstringRequired

API key for authentication

Body
themeIdstring · min: 1 · max: 128Optional

Optional saved theme to apply, using an id from GET /v1.0/themes. The theme is applied on Gamma's Standard Brand Base design for the requested format. Cannot be combined with templateId: a template or gamma keeps its own look.

Example: abcdefghi1234567
numCardsinteger · min: 1 · max: 100Optional

Target number of cards, capped at the plan's maximum (10 on free plans, 100 on paid plans); a higher value is rejected with 400. Within the cap it is a soft target: the agent may deviate by a card or two, and the result is not validated against it.

Example: 10
sourceUrlsstring · uri[] · max: 10Optional

Up to 10 http or https URLs the agent reads as source material. A link the prompt depends on, such as a Google Slides deck to import or a report to build the deck from, is required: when it cannot be read, the agent creates no gamma and the generation fails with an explanation. A link given only as background is skipped when it cannot be read.

Example: ["https://example.com/q3-report"]
promptstring · max: 400000Required

The brief: what to generate. The only required field.

Example: A 10-card investor update for Q3 covering revenue, churn, and roadmap
titlestring · min: 1 · max: 500Optional

Title for the generated Gamma. When set, it is the Gamma's saved title, whatever heading the agent writes. When omitted, the title is derived from the content.

Example: Q3 Investor Update
folderIdstringOptional

Folder to place the generated Gamma in, within the caller's workspace. Use an id from GET /v1.0/folders.

formatstring · enumOptional

Output format. Defaults to "presentation" when omitted. webpage is not supported by the agent engine and is rejected.

Example: presentationPossible values:
templateIdstring · min: 1 · max: 128Optional

Optional starting point: the id of an accessible workspace template, of a regular gamma in the workspace, or of an official Gamma template (the exploreTemplates[].id returned by GET /v1.0/templates/search). The selection works the way picking the same template or gamma in the Gamma app does: the prompt decides how the source is used, from filling its layouts with new content to borrowing only its look or moving its content onto a new design, and the source itself stays unchanged. An official template id names the currently published copy: it survives routine updates but can change when Gamma rebuilds or reintroduces the template, so rediscover it through the search endpoint if a saved id stops being accepted. Unknown, unauthorized, other-workspace, archived and retired ids are all rejected with the same 400; no other template is substituted for a rejected id.

Example: g_5hzkx0ivxsmd2ep
qualitystring · enumOptional

Quality preset: "lite", "standard", or "max" — the same presets the Gamma app offers. max requires a plan that includes it and can use more credits. Omitting the field uses the API default, capped at what the plan includes.

Example: standardPossible values:
additionalInstructionsstring · max: 5000Optional

Guidance: extra direction for the generation (tone, audience, language, style). Treated as guidance the agent aims to follow, not a constraint the output is validated against.

Example: Formal tone. Audience is the board. Keep text minimal.
exportAsstring · enumOptional

Export the finished gamma after a successful generation as a PDF, PPTX, or PNG zip. Export failure is reported as a warning on the generation, never as a failed generation.

Example: pptxPossible values:
disableConnectorsbooleanOptional

Opt this run out of workspace connector access (e.g. Notion, Slack).

Example: true
Responses
202

Generation job created

application/json
generationIdstringRequired

Unique id for the generation job, prefixed gen_.

Example: gen_V1StGXR8Z5jdHi6BPattern: ^gen_[A-Za-z0-9]+$
statusstring · enumRequired

Always "pending" on create.

Example: pendingPossible values:
post/v1.0/agent/generations
POST /v1.0/agent/generations HTTP/1.1
Host: public-api.gamma.app
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "themeId": "abcdefghi1234567",
  "numCards": 10,
  "sourceUrls": [
    "https://example.com/q3-report"
  ],
  "files": [
    {
      "uploadId": "text",
      "filename": "text",
      "purpose": "import"
    }
  ],
  "prompt": "A 10-card investor update for Q3 covering revenue, churn, and roadmap",
  "title": "Q3 Investor Update",
  "folderId": "text",
  "sharingOptions": {
    "workspaceAccess": "view",
    "externalAccess": "noAccess",
    "emailOptions": {
      "access": "view",
      "recipients": [
        "user@example.com"
      ]
    }
  },
  "format": "presentation",
  "templateId": "g_5hzkx0ivxsmd2ep",
  "quality": "standard",
  "additionalInstructions": "Formal tone. Audience is the board. Keep text minimal.",
  "exportAs": "pptx",
  "disableConnectors": true
}
{
  "generationId": "gen_V1StGXR8Z5jdHi6B",
  "status": "pending",
  "warnings": [
    {
      "code": "export_failed",
      "message": "The PPTX export failed. The generated gamma is unaffected."
    }
  ]
}

Poll GET /agent/generations/{generationId} with the returned id. Request-level warnings (for example ignored sharing or folder settings) appear on the create response and may appear again on the completed status response.

numCards is a soft target capped at your plan's maximum (10 on Free, 100 on paid plans); a higher value returns 400, and without it the agent picks a count within the same cap.

Optional themeId uses an id from GET /themes. The theme applies on Gamma's Standard Brand Base for the requested format. Do not send themeId with templateId; the request fails with 400. An unknown or inaccessible theme also returns 400.

files takes uploads from POST /uploads, such as a deck to import; see Import a presentation. A missing or expired upload returns 404, and files over 250 MiB in total return 413. An upload that can't be attached once the generation runs, such as one already attached to another generation, fails it with error.reason invalid_files; upload the files again and retry.

Optional pace sets how long the agent may work: standard (the default, up to 20 minutes) or relaxed (up to 40 minutes), which gives the agent about twice the time for more thinking, review, and finishing passes. Use relaxed for batch jobs that can wait for a better gamma. pace is separate from quality, and any combination works. Any other value, including null, returns 400. See Choose a pace.

Last updated

Was this helpful?