viral-app

viral-app

当你需要通过 viral.app API 读取或管理数据时，使用此技能。

适用场景

• 查询分析数据（账号、视频、KPI、导出）。
• 管理已跟踪的实体（账号、视频、排除项、刷新任务）。
• 管理项目和 Creator Hub 资源。
• 获取平台实时数据（Facebook、TikTok、Instagram、YouTube）。

快速开始

1. 确保已安装 viral-app CLI，且可在 PATH 中使用。

viral-app --help

2. 设置 API 密钥：

export VIRAL_API_KEY="..."

在 viral.app 控制面板的 Settings -> API Keys 中获取此密钥。

3. 验证访问权限：

viral-app accounts-list --per-page 1

除非已传入请求头，否则封装程序会自动从 VIRAL_API_KEY 注入 x-api-key。

首先收集的信息

• 任务类型：读取/报告，或修改/管理资源。
• 组织范围的 ID：orgacc_*、orgproj_*，以及相关的创作者/营销活动/付款 ID。
• 平台和实体标识符（facebook|tiktok|instagram|youtube、平台账号/视频 ID）。
• 分析任务的时间范围（--date-range[from]、--date-range[to]）。
• 分页/范围（--per-page、筛选条件），以便让输出聚焦。

命令手册

查看可用操作：

viral-app --help
viral-app <command> --help

常见读取操作：

viral-app accounts-list --per-page 10
viral-app videos-list --per-page 10
viral-app analytics-get-kpis
viral-app analytics-top-videos --per-page 10
viral-app integrations-apps-list

常见修改操作：

viral-app projects-create --body '{"name":"My Project"}'
viral-app accounts-tracked-refresh --body '{"accounts":["orgacc_..."]}'
viral-app projects-add-to-account --body '{"projectId":"orgproj_...","accountId":"orgacc_..."}'

付款修改流程：

viral-app payouts-calculate --body '{"campaignId":"orgcamp_...","creatorId":"orgcre_...","billingPeriodStart":"2026-03-01T00:00:00.000Z","billingPeriodEnd":"2026-03-31T00:00:00.000Z"}'
viral-app payouts-initiate --body '{"campaignId":"orgcamp_...","creatorId":"orgcre_...","billingPeriodStart":"2026-03-01T00:00:00.000Z","billingPeriodEnd":"2026-03-31T00:00:00.000Z","lineItems":[{"title":"Creator payout","amount":1496.62}],"calculation":{...},"integrityToken":"..."}'

付款修改规则：

• 务必在调用 payouts-initiate 前立即调用 payouts-calculate。
• 将返回的 calculation 载荷和 integrityToken 原样传入 payouts-initiate。
• 不要编造或重新计算 integrityToken。
• 如果使用 autoApproveTalentir=true，还必须设置 acknowledgeFullPayoutLiability=true，并在执行前说明风险。
• 除非用户明确要求发起或批准付款，否则付款修改应优先采用先审核的方式。

报告模板

当用户要求提供适合 Slack 的摘要或排名报告时，使用附带的报告模板：

• 排行榜模板：assets/templates/leaderboard.md
• 排行榜示例：assets/examples/leaderboard-sample.md
• Viral Video Library 模板：assets/templates/viral-video-library-report.md
• Viral Video Library 示例：assets/examples/viral-video-library-report-sample.md
• 创作者付款 + CPM 模板：assets/templates/creator-payments-cpm-report.md
• 创作者付款 + CPM 示例：assets/examples/creator-payments-cpm-report-sample.md

排行榜风格输出规则：

• 除非用户明确要求其他格式，否则遵循模板结构。
• 账号级排行榜部分使用分析账号链接。
• 视频排行榜部分使用已跟踪视频的详情链接。
• 数字应简洁易读，例如 1.4M 或 180K。
• 有可用的比较时间窗口时，使用环比趋势标记。
• 适用时，优先同时返回渲染后的报告和源 viral.app 链接。

Viral Video Library 报告规则：

• 使用指向 Viral Video Library 详情页的标题链接。
• 使用缩写指标，例如 473K 或 18.2%。
• 每个条目都要包含一行话题标签。
• 使用一行钩子，格式为 Hook (<archetype>): text + visual + audio。
• 不要使用 “Audio not surfaced” 这一表述。
• 洞察缺失时，不要编造字段；使用 not confidently detected。

创作者付款 + CPM 报告规则：

• 排名部分使用 Creator Hub 中当前正在处理、即将发放的付款。
• 使用同时按 creatorIds 和 campaigns 筛选的 Creator Hub 付款链接。
• 在有数据时，将每笔付款与同一创作者、同一营销活动最近一个已完成的付款周期进行比较。
• 组织级 KPI 变化应比较当前与前一个等长周期。
• 付款金额保持精确，观看总量使用简洁格式，Effective CPM 保留 4 位小数，每视频支出保留 2 位小数。

链接回 viral.app

当用户可以从产品界面打开数据并从中受益时，请在回复中提供直接的 viral.app 应用链接。

默认生产环境基础 URL：

https://viral.app/app

规则：

• 优先链接到应用实际支持的最具体页面。
• 对于已跟踪视频和视频库中的视频，请使用专用详情页。
• 对于账号和创作者，优先使用经过筛选的列表／仪表板视图。应用目前不提供专用的账号详情页或创作者详情页路由。
• 多值筛选条件使用单个查询参数，并以逗号分隔多个值。
• 在分析和 Creator Hub 概览页面上设置日期范围时，使用 df 和 dt，格式为 YYYY-MM-DD。
• 链接到账户或创作者相关分析页面时，保留 viewMode：
  • internal
  • competitors
  • all

常见路由：

• 按已跟踪账号筛选的分析概览：

https://viral.app/app/analytics/overview?accounts=<orgAccountId>&viewMode=internal

• 按已跟踪账号筛选的分析账号页：

https://viral.app/app/analytics/accounts?accounts=<orgAccountId>&viewMode=internal

• 按已跟踪账号筛选的分析视频页：

https://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal

• 按已跟踪账号和日期范围筛选的分析视频页：

https://viral.app/app/analytics/videos?accounts=<orgAccountId>&viewMode=internal&df=2026-03-01&dt=2026-03-18

• 已跟踪视频详情页：

https://viral.app/app/analytics/videos/tiktok/7491234567890123456

• 按创作者自有的已跟踪账号筛选的分析概览：

https://viral.app/app/analytics/overview?accounts=<orgAccountId1>,<orgAccountId2>&viewMode=all

• 按活动筛选的 Creator Hub 创作者页：

https://viral.app/app/creator-hub/creators?campaigns=<campaignId>

• 按搜索条件筛选并包含已归档／非活跃创作者的 Creator Hub 创作者页：

https://viral.app/app/creator-hub/creators?search=alex%40example.com&status=all

• 按创作者筛选的 Creator Hub 活动页：

https://viral.app/app/creator-hub/campaigns?creatorIds=<orgCreatorId>

• Creator Hub 活动详情页：

https://viral.app/app/creator-hub/campaigns/<campaignId>

• 按创作者筛选的 Creator Hub 付款页：

https://viral.app/app/creator-hub/payouts/due?creatorIds=<orgCreatorId>

• 按活动筛选的 Creator Hub 付款页：

https://viral.app/app/creator-hub/payouts/due?campaigns=<campaignId>

• 按创作者和活动筛选的 Creator Hub 即将付款列表：

https://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>&campaigns=<campaignId>

• 其他付款标签页保留相同的筛选条件：

https://viral.app/app/creator-hub/payouts/upcoming?creatorIds=<orgCreatorId>
https://viral.app/app/creator-hub/payouts/canceled?campaigns=<campaignId>
https://viral.app/app/creator-hub/payouts/paid?creatorIds=<orgCreatorId>

• 病毒式视频库筛选列表：

https://viral.app/app/library/viral-videos?search=notion&dateRange=30d&sort=views

• 按品牌／地区／最低观看次数筛选的病毒式视频库：

https://viral.app/app/library/viral-videos?brandId=<brandId>&regions=US,GB&minViews=100000&sort=outlier

• 病毒式视频库详情页：

https://viral.app/app/library/viral-videos/tiktok/7491234567890123456

可安全使用的筛选键：

• 分析概览／账号／视频：
  • accounts
  • platforms
  • projects
  • contentTypes
  • viewMode
  • df
  • dt
• 仅限分析概览：
  • publicationMode
  • topVideosBy
  • topAccountsBy
  • topCreatorsBy
  • topEntity
  • topListsPerPage
• Creator Hub 创作者：
  • search
  • campaigns
  • status
• Creator Hub 活动：
  • search
  • status
  • creatorIds
• Creator Hub 概览／活动概览：
  • campaigns
  • creatorIds
  • scope
  • publicationMode
  • df
  • dt
• Creator Hub 付款：
  • creatorIds
  • campaigns
• 病毒式视频库：
  • search
  • brandId
  • dateRange
  • sort
  • minViews
  • minOutlierFactor
  • regions
  • productTypes
  • verticals
  • formats
  • hookArchetypes
  • productDetected
  • brandDetected
  • matchedTerms

如果你还不知道正确的组织范围 ID：

• 链接到你能有把握构建的、最接近的筛选列表
• 说明链接显示的内容
• 不要臆造未知 ID 或不受支持的路径

安全规则

• 除非用户明确要求执行相应变更，否则在执行 POST、PUT、PATCH 或 DELETE 前先确认用户意图。
• 执行变更前运行 <command> --help，以确认必需的标志和请求体架构。
• 优先使用范围较窄的查询（--per-page、筛选条件、日期范围），再进行广泛导出。
• 默认保持输出为机器可读格式；仅在用户要求时切换格式。

故障排除

• 401 UNAUTHORIZED：API 密钥缺失或无效；检查 VIRAL_API_KEY 或 -H "x-api-key: ..." 的值。
• 密钥过期／已撤销或组织上下文错误，也可能导致 401。
• 429 或重试提示：稍后再试；检查 Retry-After 等响应头。
• data 数组为空：验证筛选条件、项目／账号 ID 和日期范围限制。
• 切勿在提交记录中暴露 API 密钥；测试密钥分享后应立即轮换。

Agent 默认设置

• 输出默认为 JSON（除非覆盖，否则 RSH_OUTPUT_FORMAT=json）。
• 自动分页默认为禁用（RSH_NO_PAGINATE=true），以确保脚本行为可预测。
• 读取后总结关键指标，并在执行变更后明确说明写入操作的影响。