跳到主要内容

视频任务流程

PopGo 的视频接口统一为异步任务模型。客户端提交任务后得到任务 ID，轮询任务状态，完成后读取结果地址或下载内容。

调用地址​

POST https://api.popgo.site/v1/videos
GET  https://api.popgo.site/v1/videos/{task_id}
GET  https://api.popgo.site/v1/videos/{task_id}/content
Authorization: Bearer YOUR_API_KEY

创建和查询都使用 PopGo 的公开路径。不要根据某个渠道的内部路径改写客户端请求。

通用字段​

字段类型说明
modelstring必填，使用模型与价格页中的公开模型 ID
promptstring必填，描述画面、动作、镜头和声音目标
duration / secondsinteger模型支持的时长；具体字段和固定档位看模型页
resolutionstring模型支持的分辨率，例如 480p、720p、1080p 或 4K
aspect_ratiostring模型支持的比例；不要只写在提示词里
参考素材字段array / string根据模型页使用图片、视频或音频字段

最小提交示例​

curl -X POST https://api.popgo.site/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "prompt": "清晨薄雾中的竹林，镜头缓慢向前推进",
    "seconds": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }'

创建成功后保存响应中的 id：

{ "id": "YOUR_TASK_ID", "status": "queued" }

轮询和进度​

curl https://api.popgo.site/v1/videos/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

常见状态包括：

状态含义客户端动作
queued已创建，等待处理延迟后继续轮询
in_progress正在生成读取 progress（如果返回）并继续轮询
completed生成完成读取结果 URL 或调用 /content 下载
failed生成失败读取错误信息，不要盲目重复扣费请求

任务响应可能包含 progress 百分比，也可能只返回状态。没有进度字段时，客户端应显示“处理中”而不是伪造百分比。

完成和下载​

{
  "id": "YOUR_TASK_ID",
  "status": "completed",
  "progress": 100,
  "url": "https://api.popgo.site/v1/videos/YOUR_TASK_ID/content"
}

优先使用完成响应中的 url；需要稳定下载时调用：

curl -L https://api.popgo.site/v1/videos/YOUR_TASK_ID/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

失败排查​

  • HTTP 400：检查模型 ID、字段类型、时长、分辨率、比例和参考素材数量。
  • HTTP 401/403：检查 Key、认证头和模型权限。
  • 查询 HTTP 400：确认使用的是 PopGo 返回的公开任务 ID，并调用 /v1/videos/{task_id}。
  • completed 但没有 URL：保留脱敏任务响应，检查模型页规定的结果字段和 /content 下载路径。
  • 轮询超时：降低时长或分辨率，确认上游任务确实已创建，再按指数退避继续查询。

视频计费由对应模型的价格策略决定，可能按次、按秒或按规格计费。预估额度前必须查看模型页，不要从状态轮询次数推算生成成本。

轮询、超时与重试边界​

创建请求只发送一次，立即保存 id 和提交的模型、时长、分辨率、素材模式。POST 超时可能发生在任务已经创建之后：先查任务记录，不要直接重发。查询和下载可以针对同一个 id 重试，不会因此创建第二个视频。

常规间隔3–5秒；C使用10–15秒，Kling可10秒并预留至少15分钟。遇到429、502、503或临时网络错误采用有上限的退避，并遵守 Retry-After。400参数错误先修改，401/403先修复认证或权限。达到客户端截止时间后显示“等待超时”，保存原任务以便继续查询，不把它伪装成上游失败。

progress 可能长期为0后直接100，也可能缺失；model、usage、分辨率、真实时长和fps也可能缺失。保留提交参数，实际时长/画面以下载媒体为准；缺少usage不代表免费。queued与in_progress不是失败，completed才进入下载。

结果地址可能过期或需要鉴权；优先通过PopGo的/content访问。completed后内容临时不可用时有限重试下载，不重新创建。大文件应设置足够下载超时，确认响应是视频而不是JSON错误页。不要把PopGo API Key发送到第三方媒体地址。

排错时区分五个阶段​

阶段能证明什么不能据此断定什么
界面校验素材模式、数量与来源是否被本地接受没有请求不等于上游拒绝
PopGo解析和能力校验HTTP400/500是否在任务创建前发生上游没有日志不自动证明它故障
实际发出的载荷图片/视频/音频字段和角色是否正确正确载荷不保证公网素材可读取
任务接受与轮询id、状态和错误所在阶段200或id不证明引用有效或免费
最终媒体首帧、主体、动作与声音是否采用参考仅有下载URL不证明生成质量

记录脱敏模型名、请求时间、公开任务id占位符、模式、素材数量/来源和错误短语；不得附带Key、Cookie、签名URL或完整私人素材。容量错误与内容审核错误需分别处理；即使失败也要核对实际用量和账单。先修正已知问题，再决定是否承担新的生成费用。