octen-video-search

Octen 视频搜索

通过文本查询查找网络视频。每条结果都包含匹配片段 （视频内的起止时间戳）、时长、封面图片、来源页面和作者——让你可以直接跳转到相关时刻。

目前处于 Beta 阶段。请联系我们申请 Beta 访问权限。 Octen 视频搜索目前仅限受邀用户使用 Beta 版——请通过 https://octen.ai（或 [email protected]）申请访问权限。 未获得访问权限时，调用会失败；如果发生这种情况，请告知用户该服务处于 Beta 阶段，并说明如何联系 Octen。

API 密钥设置

搜索前，请确保已设置 OCTEN_API_KEY。如果未设置，或任何调用返回 401，请停止操作，不要盲目重试：告知用户需要密钥，引导他们访问 https://octen.ai，协助他们为自己的 Agent 配置密钥，然后在密钥设置完成后继续。403 表示密钥有效，但请求被拒绝——可能是没有 Beta 访问权限，或账户余额不足；请说明这两种可能性，以及如何申请 Beta 访问权限。

为相应的 Agent 配置密钥（与其他 Octen 技能相同）：

• Claude Code — 将 { "env": { "OCTEN_API_KEY": "your-key" } } 添加到 ~/.claude/settings.json
• Cursor / 通用 shell — 在 ~/.zshrc 或 ~/.bashrc 中添加 export OCTEN_API_KEY="your-key"
• Codex — 在 ~/.codex/config.toml 的 [shell_environment_policy] 下添加 set = { OCTEN_API_KEY = "your-key" }
• OpenClaw — 将 OCTEN_API_KEY=your-key 添加到 ~/.openclaw/.env

端点

POST https://api.octen.ai/video-search

身份验证：X-Api-Key: <API_KEY> 请求头 · Content-Type：application/json

快速开始（cURL）

curl -s -X POST "https://api.octen.ai/video-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "inputs": [{"type": "text", "data": "how to tie a tie"}],
    "count": 5
  }'

使用时间筛选

curl -s -X POST "https://api.octen.ai/video-search" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${OCTEN_API_KEY}" \
  -d '{
    "inputs": [{"type": "text", "data": "GPT-5 launch keynote"}],
    "count": 10,
    "time_range": "month"
  }'

参数

参数	类型	必填	默认值	描述
inputs	数组	是	-	一个文本输入：[{"type": "text", "data": "<query>"}]（查询最多 500 个字符）
count	整数	否	5	结果数量（1–10）
time_range	字符串	否	-	相对时间范围：day、week、month、year（或 d、w、m、y）
start_time	字符串	否	-	起始时间筛选，ISO 8601
end_time	字符串	否	-	结束时间筛选，ISO 8601（必须晚于 start_time）
safesearch	字符串	否	strict	成人内容筛选：off 或 strict

响应格式

字段	类型	描述
request_id	字符串	唯一请求标识符
data.results[]	数组	视频结果列表
data.results[].title	字符串	视频标题
data.results[].url	字符串	视频 URL
data.results[].source_page	字符串	找到视频的页面
data.results[].description	字符串？	视频描述
data.results[].cover_url	字符串？	封面／缩略图图片 URL
data.results[].duration_seconds	整数？	视频总时长，单位为秒
data.results[].match_segment	对象？	匹配片段 {start_seconds, end_seconds}
data.results[].authors	字符串？	频道／作者
data.results[].time_published	字符串？	发布时间，ISO 8601
data.results[].time_last_crawled	字符串？	上次抓取时间，ISO 8601
meta.latency	数字	响应时间，单位为毫秒
meta.warning	字符串？	警告信息（如有）

错误代码

HTTP 状态	描述
400	缺少或参数无效
401	API 密钥无效或缺失
403	余额不足，或没有 Beta 访问权限
429	请求频率受限
500	内部服务器错误

注意事项

• 目前仅支持文本输入（{"type": "text", "data": "..."}）。
• match_segment 提供最相关时刻的时间戳——请展示这些时间戳，让用户可以直接跳转到该时刻。
• count 上限为 10。