本页是 FrameAI Open API 的目标 v1 合同草案，供平台实施、合作方联调和验收准备使用。端点尚未对外启用；正式发布前应生成与实现同步的 OpenAPI 规范并标注每个端点的上线状态。

统一约定

项目	目标约定
版本前缀	/open/v1。破坏性变更只进入新的主版本。
认证	Authorization: Bearer FRAMEAI_API_KEY。密钥绑定开发者应用与工作空间。
请求追踪	调用方传入 X-Request-Id；平台在响应、Webhook 和审计日志中返回该值。
幂等	所有创建型请求支持 Idempotency-Key，键在同一应用与接口范围内唯一。
时间	使用 ISO 8601 UTC，例如 2026-08-29T00:00:00Z。
分页	列表接口使用 limit 与 cursor，不使用不稳定的页码偏移。

目标响应包络：

{
  "request_id": "REQUEST_UUID",
  "data": {}
}

错误响应：

{
  "request_id": "REQUEST_UUID",
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "prompt 不能为空。",
    "details": [
      { "field": "prompt", "reason": "required" }
    ]
  }
}

目标端点

方法	路径	必需作用域	目标能力
GET	/open/v1/models	model.read	查询当前应用可调用的模型与能力。
POST	/open/v1/assets/uploads	asset.write	创建受限上传会话或取得上传目标。
GET	/open/v1/assets/{asset_id}	asset.read	查询资产状态和可访问的结果信息。
POST	/open/v1/video/generations	video.generate	创建异步视频生成任务。
GET	/open/v1/tasks/{task_id}	task.read	查询任务进度、失败详情和结果。
POST	/open/v1/tasks/{task_id}/cancel	task.cancel	在允许取消的任务阶段请求停止执行。
GET	/open/v1/account/usage	usage.read	查询应用已消耗额度与限流窗口。

视频生成任务

POST /open/v1/video/generations 的目标请求体：

{
  "workspace_id": "WORKSPACE_ID",
  "model": "MODEL_ID",
  "prompt": "主体、动作、场景、镜头语言与限制条件。",
  "aspect_ratio": "16:9",
  "duration_seconds": 5,
  "reference_asset_ids": ["ASSET_ID"],
  "webhook_url": "WEBHOOK_URL",
  "metadata": {
    "external_job_id": "CALLER_JOB_ID"
  }
}

字段规则：

• workspace_id 必须属于当前 API 密钥授权的工作空间。
• model 必须来自 GET /models 返回的可用模型列表。
• prompt、比例、时长和参考资产数量由模型能力约束；平台返回字段级错误而不是静默截断。
• reference_asset_ids 只能引用调用方被授权读取的、已准备完成的资产。
• webhook_url 必须为开发者控制台已验证的 HTTPS 域名；未传入时只允许任务查询。
• metadata 仅用于调用方关联，大小、字段数量和内容均受限制，不能存放密钥或个人敏感信息。

任务状态与结果

状态	调用方处理
queued	已接收，等待调度；保留任务 ID。
running	已开始执行；不要重复创建同一任务。
succeeded	读取 result_assets，按访问期限下载或转存结果。
failed	读取稳定错误码与可行动消息，修正输入或等待渠道恢复后再创建新任务。
cancelled	已取消；根据最终计费事件处理余额与业务状态。

目标终态响应中的关键字段：

{
  "request_id": "REQUEST_UUID",
  "data": {
    "task_id": "TASK_ID",
    "status": "succeeded",
    "result_assets": [
      {
        "asset_id": "ASSET_ID",
        "type": "video",
        "url": "SIGNED_RESULT_URL",
        "expires_at": "2026-08-29T01:00:00Z"
      }
    ]
  }
}

稳定错误码与重试

HTTP	错误码	调用方动作
400	INVALID_ARGUMENT	修正字段、模型参数或素材后创建新请求。
401	UNAUTHENTICATED	检查密钥是否缺失、撤销或使用了错误环境。
403	PERMISSION_DENIED	检查工作空间、作用域、模型授权和回调域名。
404	NOT_FOUND	检查资源 ID 是否属于当前应用和环境。
409	IDEMPOTENCY_CONFLICT	使用原始请求内容重试，或创建新的幂等键。
429	RATE_LIMITED	按响应中的重试提示退避，不并发放大重试。
5xx	UPSTREAM_UNAVAILABLE	保存 request_id，使用同一幂等键指数退避重试。

下一步：Webhook 与安全。

上一页申请与快速接入

下一页Webhook 与安全