图片与视频 API

先在模型目录选择模型，再按该模型的参数调用。模型目录统一列出当前接入的图片、视频模型和参数入口；当前价格与账号可用范围见模型与价格。

接入入口

需求	文档
查找图片与视频模型	全部模型目录
查看图片参数和参考图限制	图片模型参数
查看视频参数和参考素材限制	视频模型参数
创建、查询和下载视频	视频任务流程
直接生成图片或视频	在主站打开画布

地址与认证

OpenAI 兼容客户端的 Base URL 为 https://api.popgo.site/v1。直接 HTTP 请求使用下表完整路径，并携带 Authorization: Bearer YOUR_API_KEY。

用途	方法	路径
图片生成	POST	/v1/images/generations
图片编辑	POST	/v1/images/edits，仅限模型目录声明支持的模型

图片共用请求

将 YOUR_MODEL 替换为模型目录中的模型 ID。按该模型的参数表填写必填字段，并参考表中列出的可选字段和取值。

文生图

curl https://api.popgo.site/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "prompt": "A quiet garden at sunrise",
    "n": 1
  }'

参考图提交

参考图不是通用的可替换 URL 字段。先在型号参数中确认端点、Content-Type、字段名和数量上限，然后使用以下对应方式：

JSON 参考图：仅当型号参数表中 image 类型为 string | string[]，且参考图请求端点为 /v1/images/generations 时，将下面 image 数组加入生成请求；值可用公网图片直链或该型号支持的完整图片 Data URL。

{ "image": ["YOUR_IMAGE_URL"] }

文件参考图：仅当型号参数表中 image 类型为 file[]，且参考图请求端点为 /v1/images/edits 时，使用下面模板。多图重复 image。若素材是 URL，先下载成文件再上传；不要把 URL 字符串填进文件字段，也不要手动填写 multipart boundary。

curl https://api.popgo.site/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=YOUR_MODEL" \
  -F "prompt=Keep the subject and change the background to a garden" \
  -F "image=@reference.png"

读取响应

HTTP 200 返回结果时，遍历全部 data[]，不要只读取第一项。data[].url 是下载地址，应及时保存；data[].b64_json 是不带 Data URL 前缀的图片 Base64，解码后保存二进制文件。返回哪种形式由型号决定；仅在型号参数明确列出 response_format 时设置它。

收到 HTTP 202 时，保存 id 与响应头 Location。按 Retry-After 等待后，用同一个 API Key 对该站点的 Location 发起 GET；HTTP 200 的查询响应仍需检查 status。pending、submitted、processing 继续等待；succeeded 读取 data[]；failed 停止并读取 error；uncertain 保留原任务查询或联系支持，不自动重复生成。图片任务状态与视频任务状态不同。

HTTP 错误应先读取 error 并修正参数或素材。网络超时、202、结果下载失败均不要直接重复 POST；重新创建可能再次收费。不要把 API Key 发送到外部图片下载地址。