Skip to main content

​
基础地址与版本

本文档中的所有端点均使用：
稳定公开 API 位于 /v1 下。JSON 请求体使用 UTF-8 编码，并发送 Content-Type: application/json。 平台还在 /openai/v1 下提供 OpenAI 原生的同步图片接口，供直接使用 OpenAI Images API 的工具接入——参见 OpenAI 兼容图片接口。

​
长时间同步请求

默认域名 https://api.apipod.ai 在边缘网关配置了 120 秒 read timeout。非流式且可能超过该时长的请求——包括 OpenAI 兼容的同步图片接口（/openai/v1/images/*）——必须使用专用的长请求域名：
两个域名提供相同的路径与鉴权方式。只要请求可能运行超过两分钟，请选用 https://apid.apipod.ai；短请求、流式请求与异步任务请求使用 https://api.apipod.ai。

​
媒体端点

​
请求头与响应头

​
响应结构

图片和视频端点通常返回 APIPod 标准结构：
创建端点与状态查询端点的 data 对象并不相同。请以具体模型页或任务页的 OpenAPI 契约为准，不要假设所有媒体端点都会返回相同字段。

​
媒体创建幂等性

Idempotency-Key 是 POST /v1/images/generations 和 POST /v1/videos/generations 的可选请求头，但生产环境强烈建议使用。
  • 最大长度为 255 个字符。
  • 幂等范围包含当前 API Key、HTTP 方法和路由。
  • 使用相同键和等价 JSON 请求体时会重放已保存响应。
  • 相同键配合不同请求会返回 HTTP 409 和 idempotency_conflict。
  • 首次请求仍在处理时重试会返回 HTTP 409、idempotency_in_progress 和 Retry-After: 1。
  • 当前服务实现会保留已完成幂等记录 7 天。
新 HTTP 请求只有携带原始 Idempotency-Key 才能受到幂等保护。发送首次请求前，应先把该键与业务操作持久化保存。

​
ID 与时间戳

  • task_id 标识公开异步媒体任务，是状态查询的必需参数。
  • X-Request-ID 标识 HTTP 请求，应写入运行日志。
  • 任务状态响应中的 completed_at 是 Unix 秒级时间戳。
  • Webhook 中的 created_at 和 completed_at 是 JSON 时间戳。