gamma

用途

Gamma API 技能用于通过文本创建演示文稿、文档和网站。当用户提出「Gamma」「创建演示文稿」「生成幻灯片」「制作演示」等需求时，可调用该技能，通过 Gamma 公开 API 完成内容生成。

主要能力

该技能覆盖以下 API 能力：

Create Generation（从文本生成）：根据文本输入生成演示文稿、文档、网站或社交帖子。生成过程为异步，需使用返回的 generationId 轮询状态。
Poll Generation Status（轮询生成状态）：每 5 秒轮询一次，直至状态为 completed 或 failed。
Create Generation from Template（基于模板生成）：使用已有的 Gamma 模板生成内容，模板必须为单页文档。
List Themes（列出主题）：获取工作区可用的主题，用作生成请求中的 themeId，支持 query 搜索过滤。
List Folders（列出文件夹）：获取工作区文件夹，用作生成请求中的 folderIds。

使用方式

调用前需配置环境变量 GAMMA_TOKEN。若请求失败，可运行以下命令排查：

zero doctor check-connector --env-name GAMMA_TOKEN
zero doctor check-connector --url https://public-api.gamma.app/v1.0/generations --method POST

从文本创建生成

将请求写入 /tmp/gamma_request.json：

{
  "inputText": "Your outline or topic text here",
  "textMode": "generate",
  "format": "presentation",
  "numCards": 10,
  "textOptions": {
    "amount": "medium",
    "language": "en"
  },
  "imageOptions": {
    "source": "pexels"
  }
}

调用：

curl -s -X POST "https://public-api.gamma.app/v1.0/generations" --header "X-API-KEY: $GAMMA_TOKEN" --header "Content-Type: application/json" -d @/tmp/gamma_request.json

响应包含 generationId，用于轮询状态。

textMode 选项：

generate — AI 将输入改写为润色后的内容
condense — 压缩冗长输入
preserve — 保留原始文本结构

format 选项：presentation、document、social、webpage。

exportAs 选项（可选）：pdf、pptx、png。

轮询生成状态

每 5 秒轮询一次，直至状态为 completed 或 failed：

curl -s "https://public-api.gamma.app/v1.0/generations/<your-generation-id>" --header "X-API-KEY: $GAMMA_TOKEN"

待处理响应：

{ "generationId": "...", "status": "pending" }

完成响应：

{
  "generationId": "...",
  "status": "completed",
  "gammaId": "...",
  "gammaUrl": "https://gamma.app/docs/...",
  "exportUrl": "https://gamma.app/export/...",
  "credits": { "deducted": 5, "remaining": 195 }
}

gammaUrl 为可分享链接；exportUrl（当设置了 exportAs 时）为签名下载链接，有效期约一周。

基于模板创建生成

使用已有 Gamma 模板生成内容，模板必须为单页文档。写入 /tmp/gamma_template_request.json：

{
  "prompt": "Describe what content to fill into the template",
  "gammaId": "<your-template-gamma-id>",
  "imageOptions": {
    "style": "professional photography"
  }
}

调用：

curl -s -X POST "https://public-api.gamma.app/v1.0/generations/from-template" --header "X-API-KEY: $GAMMA_TOKEN" --header "Content-Type: application/json" -d @/tmp/gamma_template_request.json

响应包含 generationId，使用相同状态接口轮询。

列出主题

curl -s "https://public-api.gamma.app/v1.0/themes" --header "X-API-KEY: $GAMMA_TOKEN"

带搜索过滤：

curl -s "https://public-api.gamma.app/v1.0/themes?query=dark&limit=10" --header "X-API-KEY: $GAMMA_TOKEN"

将返回的 id 字段值用作生成请求中的 themeId。

列出文件夹

curl -s "https://public-api.gamma.app/v1.0/folders" --header "X-API-KEY: $GAMMA_TOKEN"

将返回的 id 字段值用于生成请求的 folderIds 数组。

高级生成选项（含主题、文件夹与分享）

写入 /tmp/gamma_request.json：

{
  "inputText": "Q1 2025 Product Roadmap\n---\nGoals\n---\nKey Initiatives\n---\nTimeline",
  "textMode": "preserve",
  "format": "presentation",
  "themeId": "<your-theme-id>",
  "folderIds": ["<your-folder-id>"],
  "exportAs": "pdf",
  "cardOptions": {
    "dimensions": "16x9"
  },
  "sharingOptions": {
    "externalAccess": "view"
  }
}

调用：

curl -s -X POST "https://public-api.gamma.app/v1.0/generations" --header "X-API-KEY: $GAMMA_TOKEN" --header "Content-Type: application/json" -d @/tmp/gamma_request.json

在 inputText 中使用 \n---\n 可手动拆分幻灯片/卡片。

适用场景

需要根据大纲或主题文本快速生成演示文稿、文档、网站或社交帖子
需要基于已有 Gamma 模板批量填充内容
需要指定工作区主题、文件夹、卡片尺寸或分享权限
需要将生成结果导出为 pdf、pptx 或 png

限制与注意事项

异步模式：生成始终先返回 generationId，必须轮询 GET /v1.0/generations/<id> 直至 completed 或 failed，建议每 5 秒轮询一次。
积分消耗：文本每张卡片消耗 1–3 积分；AI 生成图片每张消耗 2–125 积分。可在完成响应的 credits.remaining 中查看剩余积分。
速率限制：响应包含 x-ratelimit-remaining 头。遇到 429 时，暂停 30 秒以上再重试。
导出链接：签名 exportUrl 约一周后过期，如需下载请及时处理。
输入中的图片 URL：inputText 中嵌入的任何图片 URL 必须长期有效（签名 URL 需 7 天以上有效期）。
套餐要求：API 访问需要 Pro、Ultra、Teams 或 Business 套餐。