recoup-api

Recoupable API

调用 Recoupable 生产 API，获取艺人数据、社交指标、组织上下文和研究信息，并触发平台操作。

• 基础 URL： https://api.recoupable.com/api
• 适合 LLM 阅读的文档： https://developers.recoupable.com — Mintlify 网站。使用 /llms.txt 查看端点索引，使用 /llms-full.txt 查看完整内容，并使用下方列出的 OpenAPI JSON 获取机器可读的架构。

身份验证

Recoup 接受任一凭据；如果两者都存在，优先使用 API 密钥：

凭据	请求头	来源
RECOUP_API_KEY（recoup_sk_…）	-H "x-api-key: $RECOUP_API_KEY"	API 密钥安装（recoup-setup）／Agent 注册
RECOUP_ACCESS_TOKEN	-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"	有效期较短的 open-agents 沙盒令牌

构建一次 AUTH 数组，并在每次调用时重复使用：

if [ -n "$RECOUP_API_KEY" ]; then
  AUTH=(-H "x-api-key: $RECOUP_API_KEY")
elif [ -n "$RECOUP_ACCESS_TOKEN" ]; then
  AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN")
else
  echo "No Recoup credential set — ask the user to authenticate; do not retry blindly." >&2
fi
# Use as:  curl -sS "${AUTH[@]}" "https://api.recoupable.com/api/artists/{id}/socials"

如果两者均未设置，则用户尚未通过身份验证——请告知用户登录，而不是重试。（下文示例直接使用 Authorization: Bearer $RECOUP_ACCESS_TOKEN；如果使用 API 密钥，请替换为 "${AUTH[@]}"。）

处理艺人任务——先选择模式

处理任何艺人任务前，先判断用户指的是以下哪一种情况。在这里猜测，正是导致 Agent 虚构不存在的艺人（或为已有艺人编造人设）的原因。

模式	用户的意思是……	触发短语	操作
A · 任意艺人（研究）	查找任意艺人——不一定属于他们	“研究 X”“X 最近怎么样”“比较 X 和 Y”	使用研究端点（或 recoup-artist-research 技能）。只需艺人姓名——无需查询名册。
B · 浏览我的名册	列出他们账户中的艺人	“我的名册”“我的艺人”“我有哪些艺人”“从我的艺人中选一个”	执行下方的名册发现，然后展示列表。
C · 某位名册中的艺人	对他们的某位艺人执行操作	“为 <name> 制作内容”“更新 <name> 的品牌”	执行名册发现，匹配姓名，并记录 account_id 和行 id。没有匹配项 → 该艺人尚未加入名册（可提供模式 D）。
D · 添加艺人	引入一位全新的艺人	“添加／引入／创建艺人 X”“设置一位新艺人”	使用 recoup-create-artist 技能（8 次调用的链路）。

名册发现（模式 B 和 C）

在包含已填充 artists/ 目录树的 open-agents 沙盒中，该文件系统是权威数据源——使用 recoup-artist-workspace 技能，而不是 API。其他情况（API 密钥安装或没有 artists/ 目录），请通过 API 枚举：

BASE="https://api.recoupable.com/api"   # AUTH set per the Authentication section above

# 1. Whose account is this credential? Sanity-check BEFORE trusting the roster.
curl -sS "${AUTH[@]}" "$BASE/accounts/id"            # -> {"accountId":"…"}

# 2. Organizations on the account
curl -sS "${AUTH[@]}" "$BASE/organizations" \
  | jq -r '.organizations[] | [.organization_id, .organization_name] | @tsv'

# 3a. Artists for one org (preferred when you know the org)
curl -sS "${AUTH[@]}" "$BASE/artists?org_id=$ORG_ID" \
  | jq -r '.artists[] | [.name, .account_id, .id] | @tsv'

# 3b. …or every artist the account can see (account-wide)
curl -sS "${AUTH[@]}" "$BASE/artists" \
  | jq -r '.artists[] | [.name, .account_id, .id] | @tsv'

已验证的字段结构（线上环境，2026-06-07）：每个组织行都包含 organization_id、organization_name 和自身的行 id——将 organization_id 的值作为 org_id 传入。每个艺人行都包含 name、account_id 和行 id。请记录两个艺人 ID：内容端点和 /api/artists/{…}/socials 使用 account_id；行 id 是艺人的主键。

停止规则——绝不虚构名册

如果 GET /accounts/id 返回的账户邮箱为 agent+…@recoupable.com（请检查 GET /api/accounts/{accountId}），或者 organizations 和 artists 的返回结果都为空（[]），那么你几乎可以确定使用的是一次性／Agent 注册密钥，而不是用户的真实账户。请停止并说明情况：指出解析得到的 accountId，并向用户索要与其真实账户绑定的密钥（或请用户运行 recoup-setup）。不要为了继续任务而虚构艺人、人设、EP 或名册——名册为空意味着凭据存在问题，应当明确指出，而不是把它当作一张白纸来填写。

组织范围限定（RECOUP_ORG_ID）

在沙盒中运行时，环境还会提供 RECOUP_ORG_ID — 即该沙盒所属的组织。访问令牌的范围是账户级别（涵盖该账户所属的所有组织），因此将其用于未指定范围的列表端点（例如 GET /api/artists）时，返回结果会包含该账户所有组织的数据，而不只是当前沙盒对应组织的数据。这种范围不匹配会让账户用户感到意外。

设置了 RECOUP_ORG_ID 时，请在列表／查询端点中指定该组织范围：

# Artists for this sandbox's org only
curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  "https://api.recoupable.com/api/organizations/$RECOUP_ORG_ID/artists"

对于 Recoup CLI，在支持此选项的命令中传入 --org "$RECOUP_ORG_ID"。如果未设置 RECOUP_ORG_ID，说明你不在 open-agents 沙盒中 — 按常规使用账户范围的调用。

资源清单 — 优先使用文件系统，API 作为后备： 在包含已填充 artists/ 目录树的 open-agents 沙盒中，优先读取本地目录树，而不是调用 API — 对该沙盒而言，文件系统是权威来源（参见 recoup-artist-workspace 技能）。但如果不存在 artists/ 目录 — 例如在沙盒外通过 API 密钥安装 — 文件系统就无法提供答案，此时应改用上文的名册发现。切勿仅凭文件系统为空或缺失就断定“名册为空”；请先通过 API 确认。

文档导航

所有端点按下方各节归类。先用此导航找到合适的部分，再仅获取该部分的详细文档（参见查找端点），而不是获取全部文档。

账户与身份

• 账户 — 创建／获取／更新账户，将艺人添加到账户
• 组织 — 创建／列出组织，将艺人添加到组织
• 工作区 — 创建工作区
• 订阅 — 获取订阅，创建 Stripe 结账会话
• Agent — Agent 注册、电子邮件验证
• 管理员 — 仅限管理员：Agent 注册、编码／内容 Agent 的 Slack 标签、Resend 电子邮件、Privy 登录、沙盒统计、组织仓库提交统计

艺人与内容

• 艺人 — 创建／获取／删除艺人，获取社交账号、置顶／取消置顶、获取个人资料（涵盖所有平台）、触发社交媒体抓取
• 帖子 — 获取艺人在各个平台上的帖子
• 评论 — 获取艺人的评论或特定帖子的评论
• 粉丝 — 获取艺人粉丝的社交资料
• 歌曲 — 按 ISRC 创建／获取歌曲，管理目录（CRUD + 添加／移除歌曲），通过音频 LM 分析歌曲，列出分析预设
• 内容创作 — 触发流水线、生成视频／图像／说明文字、ffmpeg 编辑、视频分析、放大、成本估算、音频转录、模板

研究（Songstats + Web）

一个部分涵盖大多数音乐行业的查询工作。由 Songstats 提供支持 — 实体 ID 是短字母数字字符串（例如 wjcgfd9i），而非数字 Chartmetric ID：

• 发现：搜索（type=artists|tracks|labels）、个人资料、相似艺人、人员搜索、按 URL 查询
• 目录：专辑、曲目、曲目详情、曲目播放列表
• 指标：平台指标（16 个来源）、受众人口统计、职业生涯时间线、里程碑
• 展示：播放列表收录情况
• 洞察：AI 洞察、社交 URL
• Web：补充信息、提取 URL、深度研究、网络搜索

Songstats 迁移后已移除（这些接口会返回 404 — 请勿调用）：discover、rank、听众 cities、charts、playlist（单数）、venues、radio、festivals、genres、curator、instagram-posts。地理信息现在来自 audience，发现功能来自 similar + web。

社交集成

• 社交媒体 — 获取个人资料中的社交帖子，触发抓取
• Instagram 集成 — 评论、个人资料（批量）
• Spotify 集成 — 搜索、艺人、艺人专辑、艺人热门曲目、专辑
• Twitter/X 集成 — 搜索推文、获取趋势
• 连接器 — 列出、授权或断开第三方 OAuth 集成
• 连接器操作 — 通过共享连接执行外部操作（编辑 Google Docs/Sheets/Drive、Gmail、TikTok、Instagram）。请参阅下文。
• Apify 集成 — 抓取器运行结果
• 转录 — Whisper 音频转录

聊天与 Agent

• 聊天 — 创建/获取/删除聊天、消息、AI 生成/流式传输（兼容 Vercel AI SDK）、更新、复制、压缩
• 内容 Agent — Slack webhook + 任务回调（内部）
• 脉冲 — 列出/更新脉冲
• 通知 — 向已验证身份的账户发送通知邮件
• 任务 — 创建/获取/更新/删除计划任务，获取任务运行历史
• 图像生成 — 独立的 AI 图像生成（也可在内容创作下按范围使用）

开发者与基础设施

• 沙箱 — 创建/设置/列出/删除沙箱，获取文件内容，上传文件，更新快照

指南（非端点页面）

身份验证 · CLI · MCP · 快速入门。

OpenAPI 规范

主要部分的机器可读架构：accounts.json、social.json、releases.json、research.json、content.json（位于 https://developers.recoupable.com/api-reference/openapi/<name>.json）。

查找端点

确定所属部分后，只获取该部分的文档，而不是整个索引。示例模式：

# Find the exact path + params for a specific endpoint
curl -s https://developers.recoupable.com/llms-full.txt | grep -A 30 -i "similar artists"

# Pull the OpenAPI schema for one area
curl -s https://developers.recoupable.com/api-reference/openapi/research.json | jq '.paths | keys'

不要猜测确切的路径、参数名称或响应结构——请先获取相关部分。

请求示例

# Get all socials for an artist
curl -sS -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  "https://api.recoupable.com/api/artists/{artistId}/socials" | jq

沙箱中已预装 jq。

多步骤工作流

对于需要按特定顺序执行的多端点流程，请遵循已发布的工作流指南，不要自行编造调用链。指南会说明每一步要调用哪个端点、需要为下一步捕获哪些内容，以及哪些步骤会在沙箱环境中有意跳过。

工作流	指南	驱动程序
创建并研究一位新艺人（完整信息补全流程——POST 艺人、Spotify 匹配、个人资料/社交账号/知识库，通过 Songstats 个人资料/职业生涯/播放列表 + 网页进行结构化研究，综合整理知识库）	https://developers.recoupable.com/workflows/create-artist	recoup-artist-workspace 技能 — 构建 RECOUP.md 检查清单文件，并在每一步完成后勾选

触发加载工作流指南的情形：任何类似“创建一位新艺人”“为 X 办理入驻”“添加这位艺人”的表达，或任何需要调用多个端点才能完成的请求。

对于 create-artist 调用链，请先调用 recoup-artist-workspace 技能——它会构建 artists/{slug}/RECOUP.md，为每个工作流步骤添加一个复选框，然后 Agent 根据该文件驱动执行（每一步完成后勾选，并将输出保存到 frontmatter）。上方的工作流指南提供逐条 curl 请求参考，说明每一步的请求结构；但检查清单才是已完成事项的唯一依据。该调用链包含 8 个顺序调用，跳过任何一步都会导致艺人信息不完整。

连接器操作（Google Docs/Sheets/Drive、Gmail、TikTok、Instagram）

对于 Recoup 之外的读取/写入操作——例如通过 URL 编辑 Google 文档、将沙盒文件与 Drive 同步、发送邮件或发布 TikTok 内容——请使用平台共享的第三方连接，通过以下两个端点执行：

• GET /api/connectors/actions — 所有可用操作的目录，包含每个操作的 slug、description、parameters JSON Schema、connectorSlug 和 isConnected。请参阅文档。
• POST /api/connectors/actions — 使用与其 Schema 相匹配的 parameters，通过 actionSlug 执行一个操作。请参阅文档。

Slug 一律采用大写蛇形命名法（例如 GOOGLEDOCS_INSERT_TEXT_ACTION、GMAIL_FETCH_EMAILS）。认证方式相同，使用 RECOUP_ACCESS_TOKEN Bearer 令牌。执行操作前，务必先从目录获取参数 Schema——Composio 的参数结构因操作而异。

示例：Google 文档 ↔ 沙盒文件同步

当用户粘贴 docs.google.com/document/d/{ID}/edit URL 时，提取 ID 并选择合适的 Google Docs 操作：读取用 GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT，替换整个文档用 GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN，在指定索引处插入用 GOOGLEDOCS_INSERT_TEXT_ACTION，查找并替换用 GOOGLEDOCS_REPLACE_ALL_TEXT：

DOC_ID=$(echo "$DOC_URL" | sed -nE 's|.*/document/d/([^/]+).*|\1|p')
EXEC="https://api.recoupable.com/api/connectors/actions"
AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" -H "Content-Type: application/json")

# Read the doc into a local file.
curl -sS -X POST "${AUTH[@]}" "$EXEC" \
  -d "$(jq -n --arg id "$DOC_ID" '{actionSlug:"GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT", parameters:{document_id:$id}}')" \
  | jq -r '.result.data.text' > artists/$ARTIST_SLUG/notes.md

# (edit notes.md locally — agent edits, git diff, etc.)

# Push it back, replacing the doc's content.
curl -sS -X POST "${AUTH[@]}" "$EXEC" \
  -d "$(jq -n --arg id "$DOC_ID" --rawfile md artists/$ARTIST_SLUG/notes.md \
        '{actionSlug:"GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN", parameters:{document_id:$id, markdown_content:$md}}')"

Google 文档和本地文件是同一内容的两种视图——将本地副本与该艺术家的其他工作区文件一并提交。

**触发判断：**外部 URL（docs.google.com、drive.google.com、sheets.google.com），或“编辑此文档”“发送邮件”“在 TikTok 上发布”等短语。内部 Recoup 资源（艺术家、社交账号、研究）请使用上方 Docs Map 中的专用端点。

故障排除

错误	含义	解决方法
401	Token 缺失、无效或已过期	检查是否已设置 RECOUP_ACCESS_TOKEN；如果提示词已运行很长时间，请让用户重新发送
403	用户无权访问该资源	确认用户有权访问正在查询的组织/艺术家
404	未找到端点	重新检查上方的 Docs Map；端点可能已迁移或更名
5xx	服务器错误	重试一次；如果问题仍然存在，请告知用户状态

不应使用此技能的情况

• 读取/写入沙盒内的文件——请使用文件系统工具。
• 直接调用 Songstats、Chartmetric、Spotify 或其他第三方 API——优先使用上方 Recoup 的研究端点（这些端点会包装当前配置的研究服务提供方 Songstats，并使用我们的认证），或在有专用技能时使用该技能。
• 读取用户 Git 仓库的内容——该仓库已挂载在工作目录中。