Virlo

面向短视频的社交媒体情报工具 —— 病毒内容的彭博社。

主页：https://dev.virlo.ai

源代码：https://github.com/CalciferFriend/virlo-skill

完整 API 文档：https://dev.virlo.ai/docs | 体验平台：https://dev.virlo.ai/docs/playground

配置

设置环境变量 VIRLO_API_KEY。您的 API 密钥格式为 virlo_tkn_<your_key>，可在 [Virlo 控制台](https://dev.virlo.ai/dashboard) 中获取。

上下文

Virlo API 提供跨 YouTube、TikTok 和 Instagram 平台的分析数据。主要功能包括：

• 话题标签 —— 超过 50 万个话题标签，按使用次数和总播放量排名
• 趋势 —— 每日精选的趋势话题，每日凌晨 1 点（UTC）更新
• 视频 —— 超过 200 万条病毒式传播视频的表现数据（播放量、点赞数、分享数、评论数）
• Orbit —— 基于关键词的社交监听，支持异步分析任务
• Comet —— 自动化垂直领域监控，支持定时抓取

API 访问

所有端点均使用基础地址 https://api.virlo.ai/v1，命名采用 snake_case，返回数据格式为 { "data": ... } 包装。

发送请求

直接使用 curl 并通过 VIRLO_API_KEY 环境变量进行认证：

# GET 请求
curl -s -X GET "https://api.virlo.ai<endpoint>" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"

# POST 请求并附带 JSON 请求体
curl -s -X POST "https://api.virlo.ai<endpoint>" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '<json-body>'

示例

# 获取热门话题标签列表
curl -s -X GET "https://api.virlo.ai/v1/hashtags" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"

# 获取前 10 条爆款视频
curl -s -X GET "https://api.virlo.ai/v1/videos?limit=10" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"

# 获取每日趋势摘要
curl -s -X GET "https://api.virlo.ai/v1/trends" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"

# 创建一个 Orbit 搜索任务
curl -s -X POST "https://api.virlo.ai/v1/orbit" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI research","keywords":["artificial intelligence","AI tools"]}'

API 参考

认证

所有请求必须包含 Bearer Token：

Authorization: Bearer virlo_tkn_<your_key>

请勿将 API 密钥提交至版本控制系统。若密钥泄露，请立即在控制台中重新生成。

响应结构

所有响应均采用 { "data": ... } 包装。列表类端点包含分页元数据：

{
  "data": {
    "total": 500,
    "limit": 50,
    "offset": 0,
    "items": [ ... ]
  }
}

分页

列表类端点使用基于偏移的分页，通过 limit 和 page 查询参数实现：

通过分页最多可访问 1000 条结果。

常用查询参数

多个视频相关端点支持以下过滤条件：

平台说明

• youtube —— YouTube Shorts 及视频
• tiktok —— TikTok 视频
• instagram —— Instagram Reels

话题标签

Virlo 跟踪超过 50 万个话题标签，按使用频率和总播放量进行排名。

获取话题标签列表

GET /v1/hashtags

标准分页（支持 limit、page 参数）。

响应示例：

{
  "data": [
    {
      "hashtag": "#shorts",
      "count": 10926,
      "total_views": 869912593
    }
  ]
}

趋势

每日精选的趋势话题，每日凌晨 1 点（UTC）更新。

获取趋势组列表

GET /v1/trends

标准分页（支持 limit、page 参数）。

响应示例：

{
  "data": [
    {
      "id": "b88c0c23-8501-4975-a1e9-b7c1160c6342",
      "title": "Trends for Oct 15th",
      "trends": [
        {
          "id": "132ea402-804d-4515-b706-f3ff9c698c5e",
          "trend_id": "8ab75d1a-cb50-4885-b9b3-2e4ede2a3620",
          "trend_group_id": "b88c0c23-8501-4975-a1e9-b7c1160c6342",
          "ranking": 1,
          "trend": {
            "id": "8ab75d1a-cb50-4885-b9b3-2e4ede2a3620",
            "name": "NBA Season Opening Night",
            "description": "The 2025-26 NBA season officially tipped off...",
            "trend_type": "content"
          }
        }
      ]
    }
  ]
}

趋势条目字段：id、trend_id、trend_group_id、ranking，以及 trend（对象，包含 id、name、description、trend_type）。

200万+ 条跨 YouTube、TikTok 和 Instagram 的爆款视频。

获取热门视频（跨平台）

GET /v1/videos

平台专属接口

GET /v1/youtube-videos
GET /v1/tiktok-videos
GET /v1/instagram-videos

参数与响应结构与 /v1/videos 相同，但仅返回指定平台的数据。

视频对象字段

Orbit — 社交监听

基于关键词创建视频发现任务，支持异步分析、Meta 广告采集及创作者异常行为检测。

创建 Orbit 搜索任务

POST /v1/orbit

列出 Orbit 搜索任务

GET /v1/orbit

分页列出所有搜索任务。使用标准的 limit/page 参数。

获取 Orbit 搜索结果

GET /v1/orbit/:orbit_id

轮询直至任务完成。当 run_analysis: true 时，返回包含 AI 分析报告。

查询参数：order_by（可选值：views、likes、shares、comments、bookmarks、publish_date、author.followers），sort（asc/desc）。

响应字段：name、keywords、analysis（AI 分析报告，Markdown 格式，就绪后提供）、results（包含 total_videos、各平台视频数量、trends、videos、ads、creators）。

获取 Orbit 视频列表（分页）

GET /v1/orbit/:orbit_id/videos

标准分页，额外支持 min_views、platforms、start_date、end_date、order_by、sort 参数。

获取 Orbit 广告数据

GET /v1/orbit/:orbit_id/ads

收集到的 Meta 广告数据（需启用 enable_meta_ads: true）。支持分页，以及 order_by（created_at、page_like_count）、sort 参数。

获取创作者异常值

GET /v1/orbit/:orbit_id/creators/outliers

表现远超粉丝基数的创作者。outlier_ratio 越高，表示内容传播范围越超出其粉丝基础。支持标准分页。

Comet — 自动化领域监控

创建领域配置，按计划自动发现视频、广告及创作者异常值。

# Skill: Virlo 短视频训练数据

版本：1.0.1
分块：3/3

## 配置字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 描述性名称（例如："科技评测"） |
| `keywords` | string[] | 是 | 搜索关键词（1-20个） |
| `platforms` | string[] | 是 | 平台：`youtube`、`tiktok`、`instagram` |
| `cadence` | string | 是 | 执行频率：`daily`、`weekly`、`monthly` 或 Cron 表达式 |
| `min_views` | integer | 是 | 最小播放量阈值 |
| `time_range` | string | 是 | 时间范围：`today`、`this_week`、`this_month`、`this_year` |
| `is_active` | boolean | 否 | 默认为 true。设为 false 可暂停配置 |
| `meta_ads_enabled` | boolean | 否 | 启用 Meta 广告数据采集（默认：false） |
| `exclude_keywords` | string[] | 否 | 要排除的关键词 |
| `exclude_keywords_strict` | boolean | 否 | 是否同时检查视频字幕内容进行排除（默认：false） |

## 获取 Comet 配置列表

GET /v1/comet

添加 `?include_inactive=true` 可包含已停用的配置。

## 获取 / 更新 / 删除 Comet 配置

GET /v1/comet/:id

PUT /v1/comet/:id # 完全替换 —— 必须提供所有必填字段

DELETE /v1/comet/:id # 软删除，返回 204

## 获取 Comet 视频数据

GET /v1/comet/:id/videos

支持标准分页，以及以下参数：`min_views`、`platforms`、`start_date`、`end_date`、`order_by`、`sort`。

## 获取 Comet 广告数据

GET /v1/comet/:id/ads

需启用 `meta_ads_enabled: true`。支持标准分页，以及以下参数：`order_by`（可选：`created_at`、`page_like_count`）、`sort`。

## 获取创作者异常值

GET /v1/comet/:id/creators/outliers

支持标准分页。

---

### 错误处理

| 状态码 | 名称 | 说明 |
|--------|------|------|
| 200 | OK | 请求成功处理 |
| 201 | Created | 资源已创建 |
| 202 | Accepted | 异步任务已接收（如：Orbit 搜索任务） |
| 204 | No Content | 成功删除 |
| 400 | Bad Request | 请求参数无效 |
| 401 | Unauthorized | 缺失或无效 API Key |
| 403 | Forbidden | 权限不足 |
| 404 | Not Found | 资源不存在 |
| 422 | Unprocessable Entity | 语法正确但无法处理 |
| 429 | Too Many Requests | 请求频率超限 |
| 500 | Internal Server Error | 服务器内部错误 |

错误响应格式：

{

"error": {

"type": "validation_error",

"message": "keywords is required",

"param": "keywords"

}

}

### 速率限制

- 单次请求最大 `limit`：100 项
- 单次查询最多可访问结果数：1,000 项
- 出现 `429` 错误时，请根据 `retry_after` 值（单位：秒）等待后重试