Star API

Star API 开发者指南

面向含 Star API 的合作方账户的外部开发者。用本指南把你们的平台接到 Star：接收提案、跟踪活动状态、审阅带匹配度的短名单、拉取交付资产、监听 Webhook。你只能看到合作方密钥范围内的数据。

基址/api/star/v1

认证Bearer star_live_… / star_test_…

认证

每个请求都需要报价中含 Star API 时签发的合作方 API 密钥。正式密钥以 star_live_ 开头，沙箱以 star_test_ 开头。在后台创建时只显示一次，请像其他密钥一样妥善保存。

Authorization: Bearer star_live_…

密钥限定响应范围。你只能拿到挂在本合作方账户下的简报、短名单与创作者。Star 不是公开名册浏览接口。

简报与活动流水线

从你们一侧提交活动简报，再读取 Branch B 制作进度。阶段按以下顺序推进： RECEIVED → REVIEWED → PITCHED → GREENLIT → PRE_PROD → LIVE → DELIVERED.

POST /briefs

{
  "title": "Summer launch PV",
  "brief": "Music-led campaign for JP + EN audiences…",
  "brand": "Acme",
  "ownerName": "Maya Chen",
  "budgetNote": "Premium",
  "genres": ["J-pop"],
  "formats": ["Music video"],
  "languages": ["Japanese", "English"]
}

GET /briefs · GET /briefs/:id

列出简报或按 id 获取。响应含流水线时间戳、daysInStage、逾期标记、短名单席位与交付资产。

PATCH /briefs/:id

更新你们集成需要的字段（例如负责人显示名等）。

{ "stage": "PITCHED", "ownerName": "Maya Chen" }

带匹配度的创作者短名单

不会开放可浏览的创作者目录。每个简报对应一份短名单：建议创作者、匹配原因（类型、形式、语言、已验证触达）、预估播放区间，以及席位状态 PROPOSED / ACCEPTED / DECLINED。

POST /briefs/:id/shortlist

按简报目标与账户筛选，请求从名册自动提案席位。

{ "action": "propose", "limit": 5 }

或自行附加创作者并设定席位决定：

{
  "creatorId": "clx…",
  "seatStatus": "ACCEPTED",
  "fitNote": "Strong EN anime audience, Live2D ready"
}

GET /briefs/:id/shortlist

仅返回本简报的匹配卡片：结论、分数、匹配标签、原因、预估曝光与创作者指标。

{
  "shortlist": [{
    "status": "PROPOSED",
    "fit": {
      "verdict": "Strong fit",
      "reasons": ["Genre match: J-pop", "Language match: English"],
      "matched": { "genres": ["J-pop"], "formats": [], "languages": ["English"] }
    },
    "estimatedImpressions": { "min": 80000, "max": 150000 },
    "creator": { "id": "…", "name": "…", "reach": 32000 }
  }]
}

创作者与已验证指标

只列出已在你们短名单上的创作者。含语言、类型、形式、已验证粉丝、平均播放、增长与 lastCheckedAt。搜索也限于该合作方范围。

GET /creators?q=english
GET /creators/:id

交付资产

成片与终稿就绪后从简报拉取。可把 URL 同步到你们的 DAM 或审核队列。

PATCH /briefs/:id
{
  "asset": {
    "kind": "FINAL",
    "label": "Master 1080p",
    "url": "https://…",
    "deliveredAt": "2026-08-15T18:00:00.000Z"
  }
}

Webhook

在你们服务器注册 HTTPS 端点。事件触发时 Star 会 POST 签名载荷。若签发了密钥，请校验 X-Star-Signature（sha256=…）。

POST /webhooks
{
  "url": "https://your.app/hooks/star",
  "events": ["pitch.sent", "status.changed", "creator.accepted", "asset.ready"]
}

账户与配置

读取合作方账户，并更新集成所用筛选（最低粉丝、平台、语言、排除暂停创作者）。

GET /account
PATCH /account
{
  "config": {
    "minFollowers": 40000,
    "platforms": ["YOUTUBE"],
    "excludePaused": true,
    "languages": ["Japanese", "English"]
  }
}

导出

下载活动 CSV，用于表格或离线同步。

GET /export/briefs

事件目录

brief.created: 新简报已提交
pitch.sent: 流水线已提案或短名单已提出
status.changed: 其他阶段变更
creator.accepted / creator.declined: 创作者席位接受或拒绝
asset.ready: 交付链接已附加