2slides-ppt-generator - api-reference

2slides API 参考

2slides 幻灯片生成服务的完整 API 文档。

基础 URL

https://2slides.com/api/v1

认证

所有 API 请求需要在 Authorization 头中使用 Bearer 令牌进行认证：

Authorization: Bearer YOUR_API_KEY

从 https://2slides.com/api 获取你的 API 密钥

将 API 密钥存储在环境变量中：SLIDES_2SLIDES_API_KEY

端点

1. 生成幻灯片

根据用户输入生成幻灯片，可选择主题。

端点： POST /slides/generate

请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体：

{
"userInput": "string（必需）- 要转换为幻灯片的内容",
"themeId": "string（必需）- 来自 themes/search 的主题 ID",
"responseLanguage": "string（可选，默认：'Auto'）- 语言代码",
"mode": "string（可选，默认：'sync'）- 'sync' 或 'async'"
}

支持的语言：
Auto, English, Simplified Chinese（简体中文）, Traditional Chinese（繁體中文）, Spanish, Arabic, Portuguese, Indonesian, Japanese, Russian, Hindi, French, German, Vietnamese, Turkish, Polish, Italian, Korean

响应（同步模式）：

{
"slideUrl": "https://2slides.com/slides/…",
"pdfUrl": "https://2slides.com/slides/…/download",
"status": "completed"
}

响应（异步模式）：

{
"jobId": "abc123…",
"status": "pending"
}

注意：

• 同步模式：等待生成完成并直接返回结果（可能需要 30-60 秒）
• 异步模式：立即返回 jobId，使用 /jobs/{jobId} 轮询结果

2. 创建类似（参考图片）

生成与参考图片样式匹配的幻灯片（Nano Banana Pro 模式）。

端点： POST /slides/create-like-this

请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体：

{
"userInput": "string（必需）- 幻灯片内容",
"referenceImageUrl": "string（必需）- 参考图片的 URL 或 base64",
"responseLanguage": "string（可选，默认：'Auto'）",
"aspectRatio": "string（可选，默认：'16:9'）- 宽:高格式",
"resolution": "string（可选，默认：'2K'）- '1K'、'2K' 或 '4K'",
"page": "number（可选，默认：1）- 0 为自动检测，最大 100",
"contentDetail": "string（可选，默认：'concise'）- 'concise' 或 'standard'"
}

分辨率选项：

• 1K：标准质量
• 2K：高质量（默认）
• 4K：超高画质

内容详情选项：

• concise：简洁、关键词聚焦的内容
• standard：全面、详细的内容

页面参数：

• 设置为 0 启用自动幻灯片数量检测
• 设置为具体数字（1-100）指定确切幻灯片数量

响应：

{
"success": true,
"data": {
"jobId": "608f8997-5207-480c-9ff2-d2475cba6b9d",
"status": "success",
"message": "成功生成 N 张幻灯片",
"downloadUrl": "https://…pdf…",
"jobUrl": "https://2slides.com/workspace?jobId=…",
"createdAt": 1770108913384,
"updatedAt": 1770108934015,
"slidePageCount": 3,
"successCount": 3,
"failedCount": 0
}
}

响应字段：

• success：布尔值，表示请求是否成功
• data.jobId：唯一作业标识符
• data.status：生成状态（“success” 或 “failed”）
• data.message：人类可读的状态消息
• data.downloadUrl：直接 PDF 下载 URL（临时，1 小时后过期）
• data.jobUrl：在 2slides 工作区中查看幻灯片
• data.slidePageCount：生成的幻灯片数量
• data.successCount：成功生成的幻灯片数量
• data.failedCount：失败的幻灯片数量

注意：

• 此端点始终同步运行
• 处理时间：每页约 30 秒
• 典型响应时间：30-60 秒（1-2 页）
• 自动生成 PDF
• 匹配参考图片的样式和设计
• 超时建议：设置为 max(120, pages * 40) 秒

3. 创建 PDF 幻灯片

从文本生成自定义设计的幻灯片，可指定设计规格。

端点： POST /slides/create-pdf-slides

请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体：

{
"userInput": "string（必需）- 幻灯片内容",
"responseLanguage": "string（可选，默认：'Auto'）",
"aspectRatio": "string（可选，默认：'16:9'）- 宽:高格式",
"resolution": "string（可选，默认：'2K'）- '1K'、'2K' 或 '4K'",
"page": "number（可选，默认：1）- 0 为自动检测，最大 100",
"contentDetail": "string（可选，默认：'concise'）- 'concise' 或 'standard'",
"designSpec": "string（可选）- 设计规格（例如 'modern minimalist'）"
}

响应：

{
"success": true,
"data": {
"jobId": "608f8997-5207-480c-9ff2-d2475cba6b9d",
"status": "success",
"message": "成功生成 N 张幻灯片",
"downloadUrl": "https://…pdf…",
"jobUrl": "https://2slides.com/workspace?jobId=…",
"slidePageCount": 3,
"successCount": 3,
"failedCount": 0
}
}

注意：

• 类似于 create-like-this，但无需参考图片
• 使用 AI 根据内容和设计规格生成自定义设计
• 相同的点数成本：每页 100 点数（1K/2K），每页 200 点数（4K）
• 处理时间：每页约 30 秒
• 始终同步运行

4. 生成旁白

以单说话人或多说话人模式为幻灯片添加 AI 语音旁白。

端点： POST /slides/generate-narration

请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体：

{
"jobId": "string（必需）- 幻灯片生成的作业 ID（UUID 格式）",
"language": "string（可选，默认：'Auto'）- 旁白语言",
"voice": "string（可选，默认：'Puck'）- 可用语音名称",
"multiSpeaker": "boolean（可选，默认：false）- 启用多说话人模式"
}

可用语音（共 30 种）：
Puck, Aoede, Charon, Kore, Fenrir, Phoebe, Asteria, Luna, Stella, Theia, Helios, Atlas, Clio, Melpomene, Calliope, Erato, Euterpe, Polyhymnia, Terpsichore, Thalia, Urania, Zeus, Hera, Poseidon, Athena, Apollo, Artemis, Ares, Aphrodite, Hephaestus

响应：

{
"success": true,
"jobId": "abc123…",
"status": "pending",
"message": "旁白生成已开始"
}

注意：

• 作业必须已完成才能添加旁白
• Nano Banana 作业的作业 ID 必须为 UUID 格式
• 成本：每页 210 点数（10 用于文本，200 用于音频）
• 异步运行 – 使用 /jobs/{jobId} 轮询
• 多说话人模式使用不同语音增加多样性
• 支持 19 种语言加自动检测

5. 下载幻灯片页面和语音

将幻灯片导出为 PNG 文件，将语音旁白导出为 WAV 文件，打包为 ZIP 归档。

端点： POST /slides/download-slides-pages-voices

请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求体：

{
"jobId": "string（必需）- 幻灯片生成的作业 ID"
}

响应：

{
"success": true,
"downloadUrl": "https://…zip…",
"message": "下载已就绪"
}

归档内容：

• 页面：每张幻灯片的 PNG 文件
• 语音：WAV 音频文件（如果生成了旁白）
• 文字记录：旁白的文本转录

注意：

• 成本：完全免费（不消耗点数）
• 下载 URL 仅在 1 小时内有效
• 高质量 PNG 导出
• WAV 格式音频
• 包含所有幻灯片和语音文件

6. 搜索主题

搜索可用的演示文稿主题。

端点： GET /themes/search

请求头：

Authorization: Bearer YOUR_API_KEY

查询参数：

query: string（必需）- 搜索关键词
limit: number（可选，默认：20，最大：100）

响应：

{
"themes": [
{
"id": "theme_id_123",
"name": "Professional Blue",
"description": "Clean professional theme with blue accents",
"previewUrl": "https://…"
}
],
"count": 1
}

7. 获取作业状态

检索异步生成作业的状态和结果。

端点： GET /jobs/{jobId}

请求头：

Authorization: Bearer YOUR_API_KEY

路径参数：

jobId: string（必需）- 异步生成的作业 ID

响应：

{
"jobId": "abc123",
"status": "completed|pending|failed",
"slideUrl": "https://2slides.com/slides/…",
"pdfUrl": "https://2slides.com/slides/…/download",
"narrationStatus": "completed|pending|not_started",
"error": "error message if failed"
}

状态值：

• pending：作业仍在处理中
• completed：幻灯片已就绪
• failed：生成失败（请查看 error 字段）

旁白状态值：

• not_started：未请求旁白
• pending：旁白正在生成
• completed：旁白已就绪

轮询建议：
每 20-30 秒轮询一次，避免服务器压力

错误处理

所有端点返回标准 HTTP 状态码：

• 200 OK：请求成功
• 400 Bad Request：参数无效
• 401 Unauthorized：API 密钥缺失或无效
• 404 Not Found：资源未找到
• 429 Too Many Requests：超出速率限制
• 500 Internal Server Error：服务器错误

错误响应格式：

{
"error": "错误消息",
"code": "ERROR_CODE"
}

常见错误代码：

• INSUFFICIENT_CREDITS：账户点数不足
• INVALID_JOB_ID：作业 ID 未找到或格式无效
• RATE_LIMIT_EXCEEDED：请求过多（请参见下面的速率限制）
• JOB_NOT_COMPLETED：作业必须完成才能添加旁白
• INVALID_UUID：作业 ID 必须为 UUID 格式（适用于 Nano Banana 作业）

点数成本

• 快速 PPT（生成端点）：每页 10 点数
• Nano Banana 1K/2K（create-like-this、create-pdf-slides）：每页 100 点数
• Nano Banana 4K：每页 200 点数
• 语音旁白：每页 210 点数（10 用于文本，200 用于音频）
• 下载导出：免费（不消耗点数）

购买点数

2slides 采用按需付费点数系统，无需订阅。

点数套餐（当前促销：最高 20% 折扣）：

主要优势：

• 新用户可获得 500 个免费点数（约 50 页快速 PPT）
• 点数永不过期
• 无月订阅
• 3 天退款窗口
• 购买地址：https://2slides.com/pricing

示例成本：

• 10 页快速 PPT 演示文稿：100 点数（最大套餐下 $0.25）
• 10 页 Nano Banana 2K 演示文稿：1,000 点数（最大套餐下 $2.00）
• 10 页带旁白的演示文稿：2,100 点数（最大套餐下 $4.20）

速率限制

不同端点有不同的速率限制：

• 快速 PPT（生成）：每分钟 10 个请求
• Nano Banana（create-like-this、create-pdf-slides）：每分钟 6 个请求

最佳实践：

• 每 20-30 秒轮询异步作业，避免服务器压力
• 如果被限制（429 错误），等待后重试
• 在 https://2slides.com/api 查看套餐的速率限制

下载 URL 过期

所有下载 URL（PDF、ZIP 归档文件）仅在 1 小时内有效。生成后请及时下载文件。

最佳实践

内容格式化

为获得最佳效果，清晰结构化内容：

标题：人工智能导论

第 1 节：机器学习
– 定义
– 关键概念
– 应用

第 2 节：深度学习
– 神经网络
– 训练过程
– 用例

选择同步 vs 异步模式

• 同步模式用于快速生成（<5 张幻灯片）
• 异步模式用于大型演示文稿（>5 张幻灯片）
• 异步模式用于集成到可以轮询的工作流中

主题选择

语言支持

指定 responseLanguage 以不同语言生成幻灯片：

• "Auto" – 自动语言检测（默认）
• "English" – 英语
• "Simplified Chinese" – 简体中文
• "Traditional Chinese" – 繁體中文
• "Spanish" – 西班牙语
• "Arabic" – 阿拉伯语
• "Portuguese" – 葡萄牙语
• "Indonesian" – 印度尼西亚语
• "Japanese" – 日语
• "Russian" – 俄语
• "Hindi" – 印地语
• "French" – 法语
• "German" – 德语
• "Vietnamese" – 越南语
• "Turkish" – 土耳其语
• "Polish" – 波兰语
• "Italian" – 意大利语
• "Korean" – 韩语