摘要

这是一篇面向开发者的最小接入指南，介绍如何为 Open Video Intelligence Platform / Video AI Agent 创建 API Key，并通过最小 OpenAPI 完成视频问答、任务创建、状态查询、产物查询和用量查询。

当前版本适合做系统接入验证、开发者调试台、试点项目和内部原型。它不应被理解为完整的 /v1/videos/* 产品 API，也不建议在对外材料中承诺成熟的大规模企业级视频处理流水线。

为什么视频智能 API 不应该只返回一段摘要

很多 AI 视频工具的第一步都是“总结这个视频”。这当然有价值，但对开发者来说，只返回一段摘要通常不够。

如果要把视频理解能力接进真实产品或内部系统，至少还会遇到几个问题：

• 调用方是谁，属于哪个 workspace？
• API Key 如何创建、撤销和限制权限？
• 一次请求失败后如何追踪？
• 长任务如何查询状态？
• 结果能不能沉淀为 artifact，而不是散落在一次模型回答里？
• 用量如何记录，后续如何做成本分析或计费？

所以，一个更适合开发者接入的视频智能 API，应该不仅包含问答接口，还要包含 workspace、API Key、job、artifact 和 usage 这些基础对象。

当前支持的最小能力

当前已支持的基础能力包括：

• workspace 级 API Key 管理
• API Key 创建、查询和撤销
• /openapi/** API Key 鉴权
• POST /openapi/v1/chat/completions
• POST /openapi/v1/jobs
• GET /openapi/v1/jobs/{jobId}
• POST /openapi/v1/jobs/{jobId}/cancel
• GET /openapi/v1/jobs/{jobId}/artifacts
• GET /openapi/v1/jobs/{jobId}/usage-events

这套接口更适合先做“小范围接入验证”：用真实视频上下文、真实问题和真实业务场景，验证视频问答、产物沉淀和 API 接入链路是否跑通。

接入前准备

接入前需要准备这些信息：

项目	说明
用户账号	用于登录控制台并管理 workspace
workspaceId	API Key 绑定到具体 workspace
user JWT	创建、查看和撤销 API Key 时使用
API Key	调用 /openapi/** 时使用
测试视频上下文	可以是视频标题、字幕、转写文本或已解析的视频内容

注意：API Key 归属于 workspace。通过 OpenAPI 创建的 job、artifact 和 usage 查询都会校验 workspace 一致性。

创建 API Key

API Key 需要在已登录用户态下创建，管理接口使用用户 JWT。

POST /api/workspaces/{workspaceId}/api-keys
Authorization: Bearer <user-jwt>
Content-Type: application/json

请求示例：

{
  "name": "Developer key",
  "scopes": [
    "chat:write",
    "jobs:write",
    "jobs:read",
    "artifacts:read",
    "usage:read"
  ],
  "rateLimitPerMinute": 60,
  "allowedIps": [],
  "metadata": {
    "owner": "demo"
  }
}

创建成功后，响应中会返回明文 key。明文 key 只返回一次，调用方必须立即保存。

控制台里建议配套这些交互：

• 创建成功后弹窗展示 plainTextKey
• 提供一键复制
• 明确提示用户刷新后无法再次查看完整 key
• 数据库只保存 key 前缀和 hash，不保存原始 key

查看和撤销 API Key

查看列表：

GET /api/workspaces/{workspaceId}/api-keys
Authorization: Bearer <user-jwt>

撤销 key：

POST /api/workspaces/{workspaceId}/api-keys/{apiKeyId}/revoke
Authorization: Bearer <user-jwt>

撤销建议：

• 在 UI 中做二次确认
• 撤销后立即刷新 key 列表
• 已撤销 key 不应继续用于 OpenAPI 调用

OpenAPI 鉴权方式

开放接口挂在：

/openapi/**

调用时可以使用 X-API-Key：

X-API-Key: vag_sk_live_xxx

也可以使用 Bearer token：

Authorization: Bearer vag_sk_live_xxx

推荐开发者调试台优先使用 X-API-Key。不要把 API Key 放在 URL 参数中，也不要把真实 key 写入公开仓库、截图或教程示例。

Scope 权限说明

接口	需要 scope
POST /openapi/v1/chat/completions	chat:write
POST /openapi/v1/jobs	jobs:write
GET /openapi/v1/jobs/{jobId}	jobs:read
POST /openapi/v1/jobs/{jobId}/cancel	jobs:write
GET /openapi/v1/jobs/{jobId}/artifacts	artifacts:read
GET /openapi/v1/jobs/{jobId}/usage-events	usage:read

试点阶段可以先创建一个覆盖上述 scope 的开发者 key。正式集成时再按最小权限拆分，例如只给某个服务 jobs:write 和 jobs:read，只给数据后台 usage:read。

调用 Chat Completions

Chat Completions 适合做同步问答或调试体验，例如“总结这个视频的核心观点”。

POST /openapi/v1/chat/completions
X-API-Key: vag_sk_live_xxx
Content-Type: application/json

请求示例：

{
  "requestId": "req_openapi_chat_001",
  "projectId": "proj_demo",
  "messageContent": "总结这个视频的核心观点",
  "title": "OpenAPI chat",
  "context": {
    "videoId": "video_demo",
    "videoTitle": "Demo Video",
    "videoContent": "视频文本或上下文"
  },
  "metadata": {
    "model_code": "gpt-4.1-mini",
    "provider": "openai"
  }
}

响应中建议重点关注这些字段：

字段	用途
requestId	请求追踪和排查
sessionId / threadId	会话或上下文关联
workspaceId / projectId	资源归属
actorType / actorId	调用主体，API Key 调用时 actorType 为 api_key
response	模型生成的回答
metadata	模型、用量、产物等扩展信息

创建 Job

Jobs 适合承载更明确的任务流程，例如异步分析、工作流验证，或后续需要查询状态和产物的场景。

POST /openapi/v1/jobs
X-API-Key: vag_sk_live_xxx
Content-Type: application/json

请求示例：

{
  "requestId": "req_openapi_job_001",
  "workflowId": "wf_chat",
  "workflowVersion": 1,
  "workflowName": "chat.workflow",
  "jobType": "chat.workflow",
  "input": {
    "message_content": "总结这个视频",
    "video_content": "demo video transcript"
  },
  "idempotencyKey": "idem_openapi_job_001"
}

注意：

• organizationId 和 workspaceId 会由 API Key 自动绑定
• 如果请求显式传入的 workspace 与 API Key 不一致，会被拒绝
• 建议为每次业务请求设置稳定的 requestId
• 可通过 idempotencyKey 降低重复提交风险

查询 Job 状态

GET /openapi/v1/jobs/{jobId}
X-API-Key: vag_sk_live_xxx

这个接口适合展示：

• 当前任务状态
• 创建时间和更新时间
• workspace / project 归属
• 任务输入和输出摘要
• 错误信息或失败原因

开发者调试台建议在创建 job 后提供“刷新状态”按钮。

取消 Job

POST /openapi/v1/jobs/{jobId}/cancel
X-API-Key: vag_sk_live_xxx

取消适合用于用户主动中断、调试中断或重复任务处理。取消是否立即生效，取决于任务当时所处的执行阶段。

查询 Artifact 产物

GET /openapi/v1/jobs/{jobId}/artifacts
X-API-Key: vag_sk_live_xxx

Artifact 可以理解为任务产生的可复用结果，例如：

• 视频摘要
• 问答结果
• 结构化提取结果
• 报告内容
• 后续可展示或下载的分析产物

建议在产品界面中把 artifact 单独展示，不要只展示模型回答。这样后续可以更容易接入知识库、文档系统或内容后台。

查询 Usage 用量

GET /openapi/v1/jobs/{jobId}/usage-events
X-API-Key: vag_sk_live_xxx

Usage 适合用于：

• 试点阶段统计调用成本
• 开发者调试时观察 token 或资源使用情况
• 后续对接计费、成本分析或内部报表

调试台可以展示：

• usage event id
• usage type
• occurred time
• model/provider 信息
• token 或资源用量
• billing 状态

推荐调试顺序

第一次接入时，建议按这个顺序：

1. 登录控制台，确认 workspace。
2. 创建 API Key，并保存 plainTextKey。
3. 调用 chat/completions，验证 API Key 鉴权和基础回答。
4. 创建一个 jobs。
5. 查询 job 状态。
6. 查询 artifacts。
7. 查询 usage-events。
8. 撤销测试 key，确认旧 key 失效。

安全注意事项

• 不要把 API Key 放进前端公开代码。
• 不要把真实 key 写进 GitHub、Gitee、CSDN、掘金文章或截图。
• 明文 key 只展示一次，创建后应立即保存。
• 生产环境建议配置 API_KEY_PEPPER。
• 正式接入时按最小权限分配 scope。
• 对外发布教程时统一使用 vag_sk_live_xxx 这类占位 key。

常见问题

API Key 和用户 JWT 有什么区别？

用户 JWT 用于登录用户管理 workspace、创建或撤销 API Key。API Key 用于开发者调用 /openapi/** 能力。

现在是否支持完整视频产品 API？

当前已支持最小 OpenAPI，适合做接入验证和试点项目。不要把它宣传成完整 /v1/videos/* 产品 API。

一个 API Key 能访问其他 workspace 的 job 吗？

不能。OpenAPI 的 job、artifact 和 usage 查询都会校验 job 所属 workspace 与 API Key workspace 一致。

创建后还能再次查看完整 API Key 吗？

不能。明文 key 只在创建响应中返回一次，后端不会保存原始 key。

什么时候用 chat/completions，什么时候用 jobs？

简单同步问答和调试优先用 chat/completions。需要任务状态、产物沉淀、用量查询或更明确工作流时，优先用 jobs。

结尾

如果你正在评估视频理解 API，建议不要只看“能不能总结视频”，而要看它能否进入真实系统：是否有 API Key、scope、job、artifact、usage 和 workspace 边界。

当前这套 OpenAPI 更适合从一个明确试点开始：准备一个视频上下文、3-5 个真实问题，先验证问答、任务状态、产物查询和用量记录是否跑通。跑通之后，再逐步扩展到更复杂的视频处理流程和业务系统集成。

相关项目

本文对应的项目方向是 Video AI Agent（Open Video Intelligence Platform / 开放视频智能平台）。

官网地址：https://www.talkaibot.com/

当前更适合做开发者 API 接入验证和真实业务试点，例如企业培训视频、会议录屏、课程内容和视频知识库场景。