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.
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}.
API key for authentication
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.
abcdefghi1234567Target 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.
10Up 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.
["https://example.com/q3-report"]The brief: what to generate. The only required field.
A 10-card investor update for Q3 covering revenue, churn, and roadmapTitle 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.
Q3 Investor UpdateFolder to place the generated Gamma in, within the caller's workspace.
Use an id from GET /v1.0/folders.
Output format. Defaults to "presentation" when omitted. webpage is
not supported by the agent engine and is rejected.
presentationPossible values: 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.
g_5hzkx0ivxsmd2epQuality 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.
standardPossible values: 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.
Formal tone. Audience is the board. Keep text minimal.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.
pptxPossible values: Opt this run out of workspace connector access (e.g. Notion, Slack).
trueGeneration job created
Unique id for the generation job, prefixed gen_.
gen_V1StGXR8Z5jdHi6BPattern: ^gen_[A-Za-z0-9]+$Always "pending" on create.
pendingPossible values: Invalid request parameters, numCards above the plan maximum, a templateId that is not an accessible template or gamma, a themeId that is not an available theme, or themeId combined with templateId
Invalid or missing API key
Insufficient credits, a quality tier the plan does not include, or access denied
A files upload does not exist or has expired
files exceed 250 MiB in total
Rate limit exceeded, or the workspace has too many in-flight agent jobs (code: workspace_concurrency_limit_exceeded, with a Retry-After header)
The service is busy; retry the request
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."
}
]
}Related
GET /agent/generations/{generationId} to poll for completion
GET /themes to look up a
themeIdPoll for results for polling patterns and rate limit guidance
Warnings for agent generation warning codes
Last updated
Was this helpful?