Image2PPT 开发者 API

把图片和 PDF 批量转换成可编辑的 PPTX。上传一批文件，我们在后台用 AI 拆解版面、还原成可编辑的文字与形状，合成一个 PPTX 给你下载。

本文面向对接方的开发同学，读完就能接入。

一分钟了解怎么用

1. 登录后进入「开发者 / API」页面创建一个 API 密钥。
2. 调 POST /api/v1/jobs 上传文件（或者给出文件链接），拿到一个任务号。
3. 每隔几秒调 GET /api/v1/jobs/{任务号} 查进度，直到状态变成 completed；也可以在提交时带上 callbackUrl，任务结束时我们主动通知你（见「完成回调」）。
4. 调 GET /api/v1/jobs/{任务号}/download 下载成品 PPTX。

如果不再需要结果，可随时调 POST /api/v1/jobs/{任务号}/cancel 请求停止后续页面。要对账或找回之前的任务，调 GET /api/v1/jobs 按时间列出。

转换是异步的：提交后立刻返回任务号，真正的转换在后台跑。别在提交那一步干等结果。

1.3.0 新增的参数全部可选。callbackUrl、pages、Idempotency-Key 请求头和按链接提交都不传时，接口行为与 1.2.0 完全一致，已有的接入代码不用改。

1.4.0：进行中的任务进度更细。progress 改为按时间计算，单页任务也会逐步上涨，且只涨不跌；查询进行中的任务时新增 pageProgress、estimatedRemainingSeconds、queueAhead 三个字段，见「进度与剩余时间」。完成回调的请求体不变。

1.5.0：逐页进度新增展示文字。pageProgress[].stepLabel 与网页使用同一份步骤文案，按请求的 Accept-Language 返回中文或英文，默认英文。仅用于原样展示，完成回调的请求体不变。

认证

拿到密钥

登录 Image2PPT 后，从账号菜单进入「开发者 / API」页面，在「API Keys」处自助创建，得到一串形如下面的密钥：

i2p_live_xxxxxxxxxxxxxxxxxxxxxxxx

密钥只在创建时完整显示一次，请当场保存好。 之后页面只会显示前几位用于辨认。密钥泄露或需要轮换时，在同一页面吊销旧的、重建新的。

怎么带

每个请求都在 HTTP 头里带上密钥：

Authorization: Bearer i2p_live_xxxxxxxxxxxxxxxxxxxxxxxx

没带或带错，会返回 401（错误码 INVALID_API_KEY）。

基础地址

https://image2ppt.com

下文所有路径都拼在这个地址后面。

统一约定

• 请求和响应的 JSON 都用 UTF-8。

• 所有错误都是同一个信封格式，HTTP 状态码 + 一个 error 对象：

  {
    "error": {
      "code": "INVALID_FILE",
      "message": "不支持的文件格式：.bmp"
    }
  }
  

  你的代码应当按 code 分支处理，message 面向人看、可能会调整措辞，别拿它做逻辑判断。

  按链接提交出错时，error 里会多一个 index，指出是第几条链接（从 0 开始）：

  {
    "error": {
      "code": "URL_FETCH_FAILED",
      "message": "无法下载这条链接",
      "index": 2
    }
  }
  

  其他错误不带这个字段。

端点

1. 提交任务 POST /api/v1/jobs

提交一批文件，创建一个转换任务。请求体有两种写法，二选一，不能混用：

• multipart/form-data：直接上传文件。
• application/json：给出文件链接，由我们去下载，见下方「按链接提交」。

multipart 字段

不传 name 时，一个文件使用清理后去扩展名的文件名；多个文件或不可用的文件名使用 Slides YYYY-MM-DD HHMMSS UTC，时间为创建时的 UTC。网页和 API 共用同一套任务名称；旧任务保留原有名称规则。

请求头

一次提交有两条上限，都要满足：

两条是独立的：40 张高清图片只有 40 页，却很容易超过 90MB。页数没满不代表能提交。

超过总体积会返回 413 PAYLOAD_TOO_LARGE。遇到它请减少单次提交的文件数量分批提交，重试同样的内容不会成功。

官方 SDK 分两种用法，行为不同：submit() / convert()（TypeScript 同名）只提交你给的这一批，会在上传前先本地核对体积和页数，超了直接报错，不会白传一遍，但不会替你拆批；要自动拆批请用 submit_all() / convert_all()（TypeScript 为 submitAll() / convertAll()），它们按体积和页数把文件切成若干次提交，每次一个任务。

成功响应 201 Created

{
  "jobId": "3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37",
  "name": "Slides 2026-10-13 143205 UTC",
  "status": "pending",
  "slideCount": 12,
  "creditsReserved": 12
}

• name：服务器分配的最终任务名称。
• slideCount：这次要转换的总页数（传了 pages 时是选中的页数）。
• creditsReserved：为这次任务锁定的积分（= 页数）。提交时锁定，完成时结算。

带 Idempotency-Key 重放同一个请求时，同样返回 201、结构相同，另带响应头 Idempotent-Replayed: true，见下方「防重复提交」。

curl 示例

curl -X POST https://image2ppt.com/api/v1/jobs \
  -H "Authorization: Bearer i2p_live_xxxx" \
  -H "Idempotency-Key: 7d9e2c4a-order-20261001-001" \
  -F "files=@slide1.png" \
  -F "files=@slide2.png" \
  -F "files=@report.pdf" \
  -F "locale=zh-CN" \
  -F "aspectRatio=16:9" \
  -F "pages=1-3,7" \
  -F "callbackUrl=https://example.com/hooks/image2ppt"

按链接提交

文件已经在对象存储或 CDN 上时，不用先下载再上传，直接把链接交给我们。请求体改成 JSON：

curl -X POST https://image2ppt.com/api/v1/jobs \
  -H "Authorization: Bearer i2p_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://cdn.example.com/deck.pdf", "https://cdn.example.com/cover.png"],
    "locale": "zh-CN",
    "aspectRatio": "auto",
    "pages": "1-3,7",
    "callbackUrl": "https://example.com/hooks/image2ppt"
  }'

规则：

• JSON 请求体不超过 64KB，超过返回 413 PAYLOAD_TOO_LARGE。除 name 外，字段值为 null 或空字符串时等同于没传；带了 name 时必须是非空的有效字符串，否则返回 400 INVALID_NAME。
• 每条链接必须是 https，长度不超过 2048，不能带用户名和密码，并且解析后必须落在公网地址上（内网、本机、云主机元数据等地址一律拒绝），规则与回调地址相同。
• 下载时最多跟随 4 次重定向，每一跳都重新检查，而且必须仍是 https。
• 文件类型按内容判断，不看对方返回的 Content-Type。下载得到的文件和直接上传的文件走同一套限制：单个超过 35MB 或合计超过 90MB 会立即中断，格式、PDF、页数超限分别返回 INVALID_FILE / INVALID_PDF / PAYLOAD_TOO_LARGE / TOO_MANY_SLIDES。
• 时限：每条链接 60 秒（含读完内容），整个请求 120 秒；同一请求最多同时下载 4 条。
• 同一账户同一时间只能有 1 个按链接提交的请求在进行，否则返回 429 RATE_LIMITED（带 Retry-After）。
• 开始下载前会先检查余额和进行中的任务数。每条链接无论下载成功与否，至少按 1 页计入每分钟 500 页的提交额度。

只要错误是某一条链接引起的——INVALID_URL、URL_FETCH_FAILED，以及下载下来的文件触发的 INVALID_FILE、PAYLOAD_TOO_LARGE——error.index 都会指出是第几条（从 0 开始）；其余错误不带这个字段。

选页 pages

只想转换 PDF 里的几页时，用 pages 指定，不必先自己拆 PDF。

• 页码指这次提交按顺序拼起来之后的页码：一张图片占 1 页，一个 PDF 占它的页数。只提交一个 PDF 时，就是 PDF 自己的页码。
• 写法：逗号分隔的单页或 起-止 区间，从 1 开始，允许空格，如 "1-3, 7"。整串不超过 1000 个字符。
• 重复或重叠的部分会合并；成品按页码从小到大排列；起 大于 止（如 5-3）算写法错误。
• slideCount 和锁定的积分按选中的页数算。选中不超过 50 页即可提交，PDF 本身可以超过 50 页。
• 成品和 pageResults[].pageNumber 里的页码是成品中的第几页，也就是第几个被选中的页。例如 pages=2,5 时，原第 5 页在成品里是第 2 页。

防重复提交 Idempotency-Key

网络超时的时候，你不知道上一次提交到底成功没有。带上 Idempotency-Key 请求头，就可以放心用同一个 key 重试：同一个请求只会建一个任务、只扣一次积分。

• key 是 1–255 个可打印 ASCII 字符（0x21–0x7E，不含空格），否则返回 400 INVALID_IDEMPOTENCY_KEY。建议每次新提交生成一个 UUID。
• 作用范围是账户：同一账户下的所有 API 密钥共用一套 key。
• 有效期：首次提交成功后 24 小时。
• 「同一个请求」的判据：按顺序的文件内容（只比字节，不比文件名）或 urls 列表，加上 locale、aspectRatio、pages、callbackUrl 和提交的 name（按名称清理后的值比较）。其余没传的字段先按默认值补齐再比较；省略 name 的历史请求仍可重放。

可能的错误

2. 查询任务状态 GET /api/v1/jobs/{jobId}

轮询这个端点看进度。

成功响应 200 OK

{
  "jobId": "3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37",
  "name": "Slides 2026-10-13 143205 UTC",
  "status": "processing",
  "progress": 54,
  "pageProgress": [
    { "pageNumber": 1, "progress": 100, "stepLabel": null },
    { "pageNumber": 2, "progress": 62, "stepLabel": "识别形状、箭头和图片" },
    { "pageNumber": 3, "progress": 0, "stepLabel": null }
  ],
  "estimatedRemainingSeconds": 280,
  "queueAhead": null,
  "slideCount": 3,
  "creditsUsed": 0,
  "creditsRefunded": 0,
  "cancellationRequested": false,
  "createdAt": "2026-07-07 08:00:00",
  "completedAt": null
}

字段

进度与剩余时间

• progress 按时间算，不按页数算：每一页按它已经走过的处理阶段、占一张典型页面总耗时的比例给出 0–100，任务的 progress 是各页的平均。所以单页任务也会一点点往上走，不会在 0 停几分钟再跳到 100。
• 只会涨，不会倒退，服务重启后也一样（重启后那一页会停在原数，等重新处理追上来再继续走）。
• 任务还在 pending / processing 时最多到 99；最后一页转完、正在组装成品时停在 99；completed 才是 100。failed 时 progress 是成功转换的页数占总页数的比例，与完成回调里的数一致。
• 某一页转换失败也算这一页处理完了，pageProgress 里记 100；它是否转成要等终局看 pageResults。
• pageProgress[].stepLabel 的类型为 string | null，是这一页当前在做什么的只读展示文字（例如「读取文字和图标」）。仅随进行中任务的 pageProgress 返回；页面未开始、已完成或已失败、没有当前快照、步骤未知或取文案失败时为 null。终局查询和完成回调都不带 pageProgress，也不带 stepLabel。
• stepLabel 的语言规则与接口错误信息相同：只看本次请求的 Accept-Language，中文返回中文，其余及未指定语言默认英文；不受网页 cookie、界面语言头或提交时的输出语言影响。
• stepLabel 仅用于原样展示，文字会随服务变化，不要据此做逻辑判断、映射阶段或推算进度。接口不提供步骤编号、步骤 id 或总步数。文案暂不可用只会返回 null，不影响任务查询。
• estimatedRemainingSeconds 是偏保守的估计（大约十次里九次会在这个时间之前完成），每次查询都重新估算，可能上下浮动。刚开始转换的头几十秒、以及排队还没开始时为 null；排队时请看 queueAhead。
• 这些数字只表示进度，不对应任何具体处理步骤；内部步骤以后会调整，请不要从数字反推步骤。

失败时的样子

{
  "jobId": "3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37",
  "name": "Slides 2026-10-13 143205 UTC",
  "status": "failed",
  "progress": 0,
  "slideCount": 2,
  "creditsUsed": 0,
  "creditsRefunded": 2,
  "createdAt": "2026-07-07 08:00:00",
  "completedAt": "2026-07-07 08:01:00",
  "error": { "code": "CONVERSION_FAILED", "message": "转换失败，请稍后重试" },
  "pageResults": [
    {
      "pageNumber": 1,
      "status": "failed",
      "error": { "code": "CONVERSION_FAILED", "message": "转换失败，请稍后重试", "retryable": true }
    },
    {
      "pageNumber": 2,
      "status": "failed",
      "error": { "code": "PAGE_NOT_ATTEMPTED", "message": "任务已结束，这一页没有转换结果", "retryable": true }
    }
  ]
}

逐页结果 pageResults

任务到终局（completed 或 failed）后，这个数组按页码顺序列出每一页的结果，长度等于 slideCount。在此之前不返回——任务还在跑的时候，「这页没转出来」和「这页还没轮到」区分不了。

（早期任务没有逐页记录，这个字段也不返回。判断时请检查字段是否存在，不要假定终局任务一定带它。）

creditsRefunded 只回答「有几页没转出来」，pageResults 回答「是哪几页」。

失败页有两种去向，靠 error.code 区分：

• PAGE_NOT_ATTEMPTED — 任务先一步结束了（被取消、超时或被服务重启打断），这一页没有转换结果：可能还没轮到，也可能正转到一半被打断。成品里没有这一页，积分已退。
• 其余错误码 — 这一页转过但没成，成品里保留的是这一页的原图（不可编辑），积分按「计费与退款」规则处理。

retryable 表示同样的图再交一次有没有可能成功。目前逐页结果里的每个失败页都是 true——下面那三个码要么是一次性的故障，要么是任务先一步结束、这页没留下结果，重交都有意义。仍然请判断这个字段而不要写死 true：以后新增的码可能带 false。

错误码

任务级 error.code（整单失败时给出）只有两个值，跟这个接口发布时一样：

逐页 pageResults[].error.code 用的是更细的一套：

为什么两层粒度不同：任务级那个字段从接口发布起就只有两个值，客户已经部署的代码是照着写的，扩大取值会让那些分支静默失效。细分放在 pageResults 里——那是新字段，没有历史包袱。

message 是给人看的一句话，会跟着你的 Accept-Language 走，不要拿它做分支判断——请判断 code。它不会夹带出错的诊断细节。

两层都可能新增错误码。请把认不出的 code 当作 CONVERSION_FAILED 处理。

可能的错误

提示：任务号只在你自己的账户内可见，别人拿不到、也查不到你的任务。

3. 取消任务 POST /api/v1/jobs/{jobId}/cancel

请求服务器停止这个任务的后续工作。这个动作是收尾式取消，不是硬切：

• 已经开始转换的页面会继续完成，成功页面会保存在最终 PPTX 中并正常计费。
• 尚未开始的页面不会再运行，对应积分退回。取消到达的那一刻恰好正在派发的页可能仍会跑完，按已完成页计费。
• 请求可以安全重试，不会重复取消或重复结算。

任务仍在收尾 202 Accepted

{
  "jobId": "3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37",
  "cancellationRequested": true,
  "finalizing": true
}

finalizing: true 表示仍有页面或 PPTX 装包正在收尾。继续轮询任务状态，直到变成 completed 或 failed。如果取消在本次请求内已经结算完，则返回 200 OK 且 finalizing: false。

取消后可能有两种终局：

• 至少保留了一页成功结果：任务为 completed，可下载部分 PPTX；未产出的页面通过 creditsRefunded 退款。
• 没有可交付页面：任务为 failed，error.code 为 JOB_CANCELLED，积分全额退回。

可能的错误

4. 下载成品 GET /api/v1/jobs/{jobId}/download

任务完成后，从这里下载 PPTX。

新任务下载响应的 UTF-8 文件名为 ${name}.pptx，网页改名后也会跟着变；不支持 UTF-8 文件名的客户端使用 ASCII 备用名 slides-<任务号前 8 位>.pptx。为避免本地文件被覆盖，请按任务号自行指定保存路径。官方 SDK 始终写到调用方指定的路径。

成功响应 200 OK，响应体就是 PPTX 二进制流（Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation）。

可能的错误

保留期：成品 PPTX 在完成后保留 7 天，过期自动清理，之后下载会返回 410 OUTPUT_EXPIRED。请在保留期内取走。（历史记录仍在，只是成品文件不再保存。）

5. 查询账户 GET /api/v1/account

成功响应 200 OK

{
  "email": "you@example.com",
  "credits": 328,
  "enterpriseCredits": [
    {
      "pagesRemaining": 300,
      "pagesTotal": 5000,
      "validUntil": "2027-10-09",
      "expiresAt": "2027-10-09T16:00:00.000Z"
    }
  ]
}

credits 是当前可用于 API 的总页数：普通积分加企业额度剩余页数，不含进行中任务已锁定的部分。企业额度从到账当天起有效 12 个月，不按月重置，网页、插件和 API 共用。API 先扣最早到期的企业额度，再扣普通积分；失败页退回原额度，到期后退回的页数作废。

enterpriseCredits 列出未到期、未停用的企业额度，按到期时间从早到晚排列；没有企业额度时为 []。pagesRemaining 是未被锁定的剩余页数，pagesTotal 是该笔到账总页数，validUntil 是最后可用的北京日期（YYYY-MM-DD），expiresAt 是次日北京 00:00 对应的 ISO 时刻。

Pro 季卡 / 年卡只能在网页和插件里用，不计入这里。能调用本接口的账号都已开通 API，普通积分不会因注册赠额到期而作废（只有从没付过费、也没开通 API 的账号，注册赠送的积分才会在 7 天后作废）。

6. 任务列表 GET /api/v1/jobs

按创建时间从新到旧列出本账户通过 API 提交、且没有在网站上删除的任务。适合月底对账，或者找回丢了任务号的任务。

查询参数（都可省略）

成功响应 200 OK

{
  "data": [
    {
      "jobId": "3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37",
      "name": "Slides 2026-10-13 143205 UTC",
      "status": "completed",
      "progress": 100,
      "slideCount": 12,
      "creditsUsed": 11,
      "creditsRefunded": 1,
      "cancellationRequested": false,
      "createdAt": "2026-10-01 08:00:00",
      "completedAt": "2026-10-01 08:03:10",
      "downloadUrl": "/api/v1/jobs/3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37/download"
    }
  ],
  "nextCursor": "eyJjIjoiMjAyNi0xMC0wMSJ9"
}

• data 里每一项和 GET /api/v1/jobs/{jobId} 的返回结构相同（进行中的任务同样带 pageProgress、estimatedRemainingSeconds、queueAhead），只是不含 pageResults。要看逐页结果，再单独查那个任务。
• 最后一页的 nextCursor 是 null。
• 对账：每项的 creditsUsed 是实际扣除的积分，creditsRefunded 是退还的积分，按需要自己加总。

curl "https://image2ppt.com/api/v1/jobs?createdFrom=2026-09-01&createdTo=2026-09-30&limit=100" \
  -H "Authorization: Bearer i2p_live_xxxx"

这个端点目前不限流，但请照样处理 429：收到时按 Retry-After 等待再重试。

可能的错误

完成回调（Webhook）

提交时带上 callbackUrl，任务结束时我们会向这个地址发一个 POST，不用再轮询。回调遵循 Standard Webhooks 规范，任何支持这个规范的校验库都能直接用。

什么时候发

任务进入 completed 或 failed 时发送。取消的任务也会落到这两种状态之一，没有单独的「已取消」状态。如果任务被我们重跑后再次结束，会以新的 webhook-id 再发一次。

地址要求

提交时就会检查，不合格返回 400 INVALID_CALLBACK_URL：

• 必须是 https，长度不超过 2048，不能带用户名和密码；端口不限。
• 域名解析出来的所有地址都必须是公网地址。内网、本机回环、链路本地（包括 169.254.169.254 这类云主机元数据地址）、组播、保留地址、文档和基准测试专用地址一律拒绝。IPv6 只接受 2000::/3 公网段，并排除其中的 NAT64（64:ff9b::/96、64:ff9b:1::/48）、6to4（2002::/16）、Teredo（2001::/32）和文档地址（2001:db8::/32）；IPv4 映射或兼容的 IPv6 地址按其中的 IPv4 判断。
• 每次投递前都会重新解析并检查，连接只发往检查通过的 IP；不跟随重定向。

请求格式

POST <callbackUrl>
Content-Type: application/json
User-Agent: Image2PPT-Webhook/1.0
webhook-id: msg_2Lx8Qe7cV1nR4tYk
webhook-timestamp: 1790841600
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

请求体：

{
  "type": "job.completed",
  "data": {
    "jobId": "3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37",
    "name": "Slides 2026-10-13 143205 UTC",
    "status": "completed",
    "progress": 100,
    "slideCount": 12,
    "creditsUsed": 12,
    "creditsRefunded": 0,
    "cancellationRequested": false,
    "createdAt": "2026-10-01 08:00:00",
    "completedAt": "2026-10-01 08:03:10",
    "downloadUrl": "/api/v1/jobs/3f2b8c1e-9a4d-4c7b-8e2f-1a6d5c0b9e37/download",
    "pageResults": [{ "pageNumber": 1, "status": "converted" }]
  }
}

• type：job.completed 或 job.failed。以后可能新增类型，认不出的类型请直接忽略（照常返回 2xx）。
• data：与 GET /api/v1/jobs/{jobId} 对终局任务的返回相同，但不含 callback 字段（也没有只在进行中才有的 pageProgress、estimatedRemainingSeconds、queueAhead）。
• 请求体在任务结束时就定下来了，每次重试的字节完全相同。
• data 里 message 的语言跟随提交那次请求的 Accept-Language。

校验签名

每个请求都要先校验签名，再相信里面的内容：

1. webhook-timestamp 与当前时间相差超过 300 秒，拒收。
2. 取密钥 whsec_ 前缀之后的那段，按标准 base64 解码，得到 HMAC 密钥。
3. 签名内容是 <webhook-id>.<webhook-timestamp>.<原始请求体>，用 HMAC-SHA256 计算，结果做标准 base64 编码。
4. 把 webhook-signature 按空格拆开，任意一个 v1, 后面的值与自己算出的相等（用恒定时间比较）即通过。

一定要用收到的原始字节计算，不要先解析 JSON 再重新序列化。只用 Python 标准库的写法：

import base64, hashlib, hmac, json, time

def verify_webhook(body: bytes, headers, secret: str) -> dict:
    # headers 需按不区分大小写的方式取值（Flask、Django、FastAPI 的 headers 都是）
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("webhook-timestamp 超出 5 分钟")

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for item in headers["webhook-signature"].split(" "):
        version, _, signature = item.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return json.loads(body)
    raise ValueError("签名不匹配")

密钥管理

每个账户一份回调密钥，形如 whsec_<base64>（前缀后是 32 个随机字节的标准 base64）。在「开发者 / API」页面查看、复制和轮换；第一次打开这个页面，或第一次提交带 callbackUrl 的任务时自动生成。

轮换后的 24 小时内，签名头会同时带新旧两个签名，你有一天时间把新密钥换上，期间不会漏收。

重试

• 你的服务在 10 秒内返回 2xx 算成功。重定向、超时、非 2xx、连接失败都算失败。你返回的响应体我们只读前几 KB。
• 最多投递 6 次：立即、1 分钟后、5 分钟后、30 分钟后、2 小时后、6 小时后。
• 待发的回调在我们的服务重启后不会丢。
• 因为会重试，同一条回调你可能收到不止一次，请按 webhook-id 去重。处理慢的逻辑建议先返回 2xx，再异步处理。

查看投递情况

带了 callbackUrl 的任务，GET /api/v1/jobs/{jobId} 和任务列表的每一项会多一个 callback 字段：

"callback": {
  "url": "https://example.com/hook",
  "status": "pending",
  "attempts": 1,
  "lastAttemptAt": "2026-10-01 08:00:00",
  "lastResponseStatus": 503,
  "nextAttemptAt": "2026-10-01 08:01:00"
}

时间都是 UTC，格式 YYYY-MM-DD HH:MM:SS；没有值时为 null。回调最终失败时，任务本身不受影响，照常查询和下载即可。

限流

按账户限流（同一账户下所有密钥共享额度）：

• 同时进行中的任务 ≤ 10 个（pending + processing）。
• 提交速率 ≤ 500 页/分钟。按链接提交时，每条链接无论下载成败，至少按 1 页计。
• 按链接提交：同一时间只能有 1 个请求在进行。

超出时返回 429（RATE_LIMITED），并在 Retry-After 响应头给出建议等待的秒数。

查询任务状态不限流。任务列表目前也不限流，但以后可能会加，请统一处理 429。

正确的应对：读 Retry-After，等这么多秒再重试，别无脑立刻重试。官方 Python 客户端的 wait() 已经内建了这个退避；若你自己直接提交，参考下面的伪代码：

import time, requests

while True:
    resp = requests.post(url, headers=headers, files=files)
    if resp.status_code != 429:
        break
    time.sleep(int(resp.headers.get("Retry-After", "5")))

撞到限流后重试时，带上同一个 Idempotency-Key 更稳妥：被拒的请求不占用 key，而万一上一次其实已经成功，也不会建出第二个任务。

版本与升级提示

官方 SDK（0.2.0 起）每个请求都会自报家门：

User-Agent: image2ppt-python/0.2.0
User-Agent: image2ppt-node/0.2.0

这个头只用于统计和联系你，不参与鉴权、不参与限流、不影响任何请求的结果。

自己写客户端的话，不用管这个头——带不带都一样，我们把所有非官方 SDK 的调用统一记成「自建客户端」，不区分语言、不记版本，也不保存你报的那串字符（所以带一个自定义的名字并不会让你的程序在我们这边更容易被认出来，这一点我们不做假承诺）。

只有一个请求：不要冒用 image2ppt-python/... 或 image2ppt-node/...。这两个字符串是官方 SDK 的身份，冒用会让「官方 SDK 占比」这个数失真，而且我们会照着它给你发升级提示——提示里指的版本你根本没在用。

如果你用的官方 SDK 版本已经低于我们仍在维护的最低版本，响应里会多带三个标准头（RFC 8594 / RFC 9745），成功的响应上也带：

Deprecation: @1793491200
Sunset: Sun, 01 Nov 2026 00:00:00 GMT
Link: <https://github.com/image2ppt/image2ppt-sdk/blob/main/CHANGELOG.md>; rel="deprecation"

• Deprecation —— 你这个版本我们准备停掉了。值是它被判定为过时的日期，按 RFC 9745 写成 @ 加 Unix 时间戳。判断"有没有这个头"就够了，不必解析它。
• Sunset —— 计划停止支持的时间（有明确日期时才会出现）。
• Link —— 改了什么、怎么升级。

**这些头只是提醒。**状态码不变，请求照常处理，不会因此被拒绝。官方 SDK 收到后会在你的日志里打一条警告（可以关掉）。真要停用某个版本，我们会提前很久单独公告，不会只靠这个头。

业务语义

异步与时延预期

提交后任务在后台跑。单页典型耗时约 2 分钟，九成任务在 3 分钟内完成。页数多的任务更久。建议轮询间隔从 5 秒起、逐步退避到 15 秒左右，不要每秒猛查。

一个任务 = 一个 PPTX

一次提交的所有文件（多张图 / 多页 PDF）会合成同一个 deck，按上传顺序排页；用了 pages 时只包含选中的页。想要多个独立 PPTX，就分成多次提交。

计费与退款

• 按页计费，1 页 1 积分。
• API 可用企业额度和普通积分：Pro 季卡 / 年卡的页数只能用于网页和插件。积分不足而账号上有卡页时，INSUFFICIENT_CREDITS 的说明会提到这一点。
• 提交时按总页数锁定相应积分（响应里的 creditsReserved）。
• 完成时结算：实际扣除体现在 creditsUsed。
• 部分成功：如果个别页转换失败、其余成功，任务仍然是 completed，成品里包含成功的页，失败页的积分自动退回，体现在 creditsRefunded（此时 creditsRefunded > 0）。
• 整体失败：任务变成 failed，锁定的积分全额退回。
• 主动取消：已开始页面完成后按同一规则结算；未开始页面不再运行并退款。若没有可交付页面，状态为 failed 且错误码为 JOB_CANCELLED。

一句话：你只为成功产出的页付费。

官方 SDK

我们提供 Python 和 Node.js/TypeScript 两个官方客户端，都封装了提交、轮询、取消、下载、429 退避和错误映射。源码、示例和变更记录在 https://github.com/image2ppt/image2ppt-sdk；安装从包页面走：Python 见 https://pypi.org/project/image2ppt/，Node.js 见 https://www.npmjs.com/package/image2ppt。

SDK 只在服务端使用。别把 API 密钥放进浏览器或任何用户能看到的地方——谁都能读出来。

Python

pip install image2ppt

from image2ppt import Image2PPTClient, Image2PPTError, JobFailedError

client = Image2PPTClient(api_key="i2p_live_你的密钥")

try:
    # 一步到位：提交 → 轮询等待 → 下载
    job = client.convert(
        ["slide1.png", "slide2.png", "report.pdf"],
        dest_path="out.pptx",
        locale="zh-CN",
        aspect_ratio="16:9",
    )
    print("完成，用掉积分：", job.credits_used, "退回：", job.credits_refunded)
except JobFailedError as e:
    print("转换失败：", e.code, e.message)
except Image2PPTError as e:
    print("请求出错：", e.status_code, e.code, e.message)

Node.js / TypeScript

需要 Node 18.17+（用内置 fetch；上传前压图用 sharp，会随包自动安装）。

npm install image2ppt

import { Image2PPTClient, Image2PPTError, JobFailedError } from "image2ppt";

const client = new Image2PPTClient({ apiKey: "i2p_live_你的密钥" });

try {
  const job = await client.convert(
    ["slide1.png", "slide2.png", "report.pdf"],
    "out.pptx",
    { locale: "zh-CN", aspectRatio: "16:9" },
  );
  console.log("完成，用掉积分：", job.creditsUsed, "退回：", job.creditsRefunded);
} catch (e) {
  if (e instanceof JobFailedError) console.error("转换失败：", e.code, e.message);
  else if (e instanceof Image2PPTError) console.error("请求出错：", e.statusCode, e.code, e.message);
  else throw e;
}

显示进度和预计时间

SDK 0.7.0 起，wait / convert 可以传一个进度回调，每次查到新状态就调用一次，带上最新的任务快照（字段见上文「查询任务状态」）和已等待的时间。创建客户端时设 accept_language="zh-CN"（Node.js 是 acceptLanguage: "zh-CN"），每页的步骤文字就是中文。

client = Image2PPTClient(api_key="i2p_live_你的密钥", accept_language="zh-CN")

def show(job, elapsed):  # elapsed：已等待的秒数
    line = f"总进度 {job.progress}%"
    if job.queue_ahead:
        line += f"，前面还有 {job.queue_ahead} 个任务"
    if job.estimated_remaining_seconds is not None:
        line += f"，预计还要约 {job.estimated_remaining_seconds} 秒"
    print(line)
    for page in job.page_progress or []:
        print(f"  第 {page.page_number} 页 {page.progress}%  {page.step_label or ''}")

job = client.convert(["slide1.png", "slide2.png"], dest_path="out.pptx", on_progress=show)

const client = new Image2PPTClient({ apiKey: "i2p_live_你的密钥", acceptLanguage: "zh-CN" });

const job = await client.convert(["slide1.png", "slide2.png"], "out.pptx", {
  onProgress: (job) => {
    console.log(`总进度 ${job.progress}%`, job.estimatedRemainingSeconds ?? "");
    for (const page of job.pageProgress ?? []) {
      console.log(`  第 ${page.pageNumber} 页 ${page.progress}%  ${page.stepLabel ?? ""}`);
    }
  },
});

要在你自己的网页上给用户显示进度条：在服务器上 submit 后立刻返回，网页每隔 3–5 秒问一次你的服务器，服务器调 get_job / getJob 把 progress、estimatedRemainingSeconds、queueAhead、pageProgress 原样转给网页。密钥始终留在服务器上。可直接运行的完整示例见 SDK 仓库的 examples/progress.py 和 examples/progress.ts。

分步控制（submit / wait / download）、账户查询（account）和各异常的完整说明见 GitHub 仓库的 README 与示例。

错误码总表

message 是给人读的，语言只跟着请求的 Accept-Language 走：说中文就给中文，不带这个头或者说别的语言一律给英文。浏览器 cookie、界面语言头这些都不影响它——从浏览器里调这个接口也一样，你声明什么就是什么。要在代码里分支请用 code，它不随语言变。