申请与快速接入

约 817 字大约 3 分钟

本页说明开放平台上线后的目标接入流程。示例中的 API_DOMAIN、FRAMEAI_API_KEY、MODEL_ID、WORKSPACE_ID 和 WEBHOOK_URL 均为占位符，不能替换为 Gateway 内部地址、服务间令牌或客户端会话凭据。

规划中

一、创建开发者应用

正式上线后，工作空间所有者或获授权管理员将在开发者控制台完成以下操作：

创建应用，填写应用名称、用途说明和所属工作空间。
选择最小所需作用域，例如 model.read、asset.write、video.generate、task.read。
为生产回调填写 HTTPS WEBHOOK_URL，并完成域名验证。
根据接入环境选择沙箱或生产凭据；两个环境的密钥、额度和资源应完全隔离。
创建 API 密钥后立即写入调用方的服务端密钥管理系统。密钥仅在创建时显示一次，不能放入浏览器代码、桌面应用包、仓库或日志。

二、请求规范

目标基础地址为：

https://API_DOMAIN/open/v1

每个请求都应携带 API 密钥和唯一请求 ID：

Authorization: Bearer FRAMEAI_API_KEY
Content-Type: application/json
X-Request-Id: REQUEST_UUID

对创建任务、创建上传会话等具有副作用的请求，额外携带调用方生成且可重试复用的 Idempotency-Key。网络超时后必须使用同一个幂等键重试，避免重复扣费或创建重复任务。

三、完整调用案例：提交并获取一个视频任务

1. 查询可用模型

curl "https://API_DOMAIN/open/v1/models?capability=video" \
  -H "Authorization: Bearer FRAMEAI_API_KEY" \
  -H "X-Request-Id: REQUEST_UUID"

从响应中选择调用方工作空间已获授权、状态为可用的 MODEL_ID。不要把管理后台中的渠道代码、内部模型映射或前端展示名称当作开放 API 模型 ID。

2. 创建视频生成任务

curl -X POST "https://API_DOMAIN/open/v1/video/generations" \
  -H "Authorization: Bearer FRAMEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: REQUEST_UUID" \
  -H "Idempotency-Key: IDEMPOTENCY_KEY" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "model": "MODEL_ID",
    "prompt": "雨后城市街角的咖啡店，镜头缓慢推进，暖光，电影感，无字幕。",
    "aspect_ratio": "16:9",
    "duration_seconds": 5,
    "webhook_url": "WEBHOOK_URL"
  }'

目标成功响应：

{
  "request_id": "REQUEST_UUID",
  "data": {
    "task_id": "TASK_ID",
    "status": "queued",
    "created_at": "2026-08-29T00:00:00Z"
  }
}

3. 轮询任务或等待 Webhook

curl "https://API_DOMAIN/open/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer FRAMEAI_API_KEY" \
  -H "X-Request-Id: REQUEST_UUID"

任务状态建议按 queued、running、succeeded、failed、cancelled 处理。正常情况下优先消费 Webhook；轮询仅作为丢失回调后的补偿，并使用递增间隔，避免短时间高频请求。

四、上线前验收

应用、密钥、工作空间、作用域和环境均匹配。
API 密钥仅保存在服务端密钥管理系统，日志中已脱敏。
任务创建请求带有唯一且可复用的 Idempotency-Key。
调用方持久化保存 request_id 与 task_id，可用于问题排查和对账。
回调服务验证签名，并能处理重复、乱序和延迟事件。
生产流量设置了调用量、失败率和余额/额度告警。

继续阅读：v1 接口合同草案与 Webhook 与安全。