Growth Studio OpenAPI接入文档 · Video Clip Editing

此接口启动异步片段替换任务。先视频状态与结果查询(查询视频详情):只有返回 supports_edit=true 且包含 edit 对象的视频才能编辑。clip_index 是服务端已保存片段的序号,从 1 开始;服务端会校验该片段存在。不支持指定任意时间区间、媒体路径或输出路径。

请求

POST /openapi/v1/videos/{video_id}/edit
Content-Type: application/json
Authorization: Bearer <API_KEY>

cURL

curl --request POST \
  "${BASE_URL}/openapi/v1/videos/627410861853514292/edit" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "clip_index": 2,
    "instruction": "Make the expression more natural."
  }'

参数

字段 类型 必填 说明
clip_index integer 是 已保存片段的序号,范围 1~40,且该片段必须存在
instruction string 是 本片段的修改要求,最多 500 字符

成功响应与结果查询

HTTP 202 Accepted 表示编辑任务已受理。继续通过 GET /openapi/v1/videos/{video_id} 查询 edit.status 和 edit.latest,直到编辑进入 succeeded、failed 或 canceled。成功后,同一视频详情中的 output.video_url 指向编辑后的成片。

响应头:

Location: /openapi/v1/videos/{video_id}
X-Request-Id: edit-video-001

响应体:

{
  "video_id": "627410861853514292",
  "edit": {
    "id": "edit_01H...",
    "status": "processing",
    "clip_index": 2,
    "instruction": "Make the expression more natural."
  },
  "request_id": "edit-video-001"
}

费用、失败与重试

先抵扣免费编辑次数,再对剩余付费编辑金额应用折扣,向上取整到美分。视频详情的 price 仍表示原始生成价格,不表示本次编辑费用。

保存 edit.id,按 source_type=video_edit、source_id=video-edit:{video_id}:{edit.id} 匹配钱包流水,通过 video_consume / video_refund 区分扣款与退款。详见费用与钱包流水(匹配视频任务)。全部免费时可能没有扣款流水。

视频当前不可编辑时可能返回 409 VIDEO_EDIT_UNAVAILABLE,先查询详情与编辑状态。接口没有调用方幂等键;请求超时或无法确认 202 响应时,先查询 edit.latest 并核对业务记录,避免重复提交和扣费。其他错误与退避规则见错误与重试。