API、CLI 和 MCP

在应用里能做的事，也可以通过代码和智能体完成：提交链接、上传文件或整个账号，等待帖子完成标注，然后查看结果。三种接入方式，共用一套接口规范。任务会异步处理，重复提交不会重复生成结果或扣费，而且操作前后都能查看费用。

快速开始

在应用的设置 → 开发者中创建 API 密钥，将密钥设为 GARFUNKEL_API_KEY，然后选择接入方式。MCP 客户端也可以通过 OAuth 登录，无需使用密钥。

shell

export GARFUNKEL_API_KEY=gma_live_…
garfunkel submit urls.txt --category sports --dry-run
garfunkel submit urls.txt --category sports --wait
garfunkel results export job_… --format jsonl

身份验证

发送 Authorization: Bearer gma_live_…，即来自API 密钥页面、限定在组织范围内使用的 API 密钥。CLI 和 MCP 会读取 GARFUNKEL_API_KEY。每个 POST 请求都可以带上 Idempotency-Key；重复请求会返回原始响应，不会重复扣费。

提交任务

提交后会立即返回任务 ID（202）。priority 可设为 standard（费用较低，耗时几分钟到几小时）或 fast。设置 dry_run: true 可免费预估费用，并逐项验证。

curl

curl -X POST https://garfunkel.gar-ai.com/api/v1/jobs \
  -H "Authorization: Bearer $GARFUNKEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "items": [{ "url": "https://www.tiktok.com/@user/video/7412345678901234567" }],
    "options": { "translate_to": "en" },
    "dry_run": true
  }'

条目状态：queued → fetching → processing → succeeded | failed | canceled。

账号任务

“@handle 自 2025-01-01 起发布的所有帖子。”团队此前没有统计过的帖子，每 20 条收取 2 美分，费用会先行预留，并在分析帖子后退回；随后任务会进入 awaiting_confirmation，并显示每个账号的 posts_found、oldest_post_at、reached_since 和 notices（例如，平台只返回某个较晚日期之后的帖子）。使用 POST /jobs/{id}/confirm 确认，或设置 options.max_credits 自动确认。

json

{
  "items": [
    { "account": "@nike", "platform": "tiktok", "since": "2025-01-01", "max_posts": 1000 },
    { "account": "https://x.com/nasa", "since": "2025-01-01" }
  ],
  "options": { "max_credits": 50000 }
}

上传文件

文件数据会直接上传到存储空间，不会经过 API。上传后 24 小时内未关联到任务的文件会被删除。

http

POST /api/v1/uploads
{ "filename": "clip.mp4", "content_type": "video/mp4", "size_bytes": 1234567 }
→ { "id": "upl_…", "upload_url": "<presigned PUT>", "method": "PUT", "headers": {…}, "expires_at": "…" }

# PUT the bytes straight to storage, then submit { "upload_id": "upl_…" } as a job item.

结果

一条已分析的帖子。只有设置 ?include=embedding 时才会返回嵌入向量。pacing 根据镜头检测结果生成（测试版）。

json

{
  "item_id": "itm_01J…",
  "job_id": "job_01J…",
  "source": { "platform": "tiktok", "url": "…", "author": "…", "posted_at": "…",
              "metrics": { "views": 0, "likes": 0, "comments": 0, "shares": 0 } },
  "caption": "…",
  "language": "es",
  "transcript": { "text": "…", "segments": [{ "start": 0.0, "end": 2.1, "text": "…" }] },
  "translation": { "language": "en", "caption": "…", "transcript": "…", "on_screen_text": "…" },
  "summary": "…",
  "tags": { "format": "…", "theme": "…", "tone": ["…"], "topics": ["…"], "keywords": ["…"] },
  "hook": { "type": "…", "timing_s": 1.2, "confidence": 0.8 },
  "pacing": { "beta": true, "shot_count": 14, "avg_shot_s": 2.1, "cuts_per_s": 0.47, "first_cut_s": 0.9 },
  "embedding": { "dims": 1024 },
  "credits_charged": 12,
  "processed_at": "…"
}

接口

接口	功能
POST /api/v1/jobs	提交链接、上传文件或账号（设置 dry_run 可免费预估费用）。
GET /api/v1/jobs/{id}	查看状态、各状态的条目数量、预留／扣除／退回的金额（美分），以及账号和通知。
GET /api/v1/jobs/{id}/items	分页查看条目；使用 ?status=failed 筛选。
POST /api/v1/jobs/{id}/confirm	为等待确认的账号任务预留费用。
POST /api/v1/jobs/{id}/cancel	取消排队中的条目；已预留的金额会退回余额。
POST /api/v1/jobs/{id}/retry	重试失败的条目（重新估价并预留费用）。
POST /api/v1/uploads	为你自己的媒体文件生成预签名 PUT 上传请求。
GET /api/v1/results	使用 job_id, platform, tag, q 筛选。
POST /api/v1/results/search	基于嵌入向量进行语义搜索。
GET /api/v1/results/export	以流式方式导出 CSV 或 JSONL。
GET /api/v1/credits	余额（以分计，另含 balance_usd）、预留金额、充值档位和消费奖励。
DELETE /api/v1/data	删除你所在组织的所有数据。

错误

所有非 2xx 响应都采用统一格式。错误代码：unauthorized, forbidden, not_found, invalid_request, insufficient_credits, rate_limited, idempotency_conflict, counting_in_progress, internal_error。

json

{ "error": { "code": "insufficient_credits",
             "message": "Job needs $1.80; your balance is 42¢.",
             "details": { "required": 180, "balance": 42 },
             "retryable": false } }

单项失败代码保持不变，且不会扣费：

post_not_found	这条帖子已不存在。
post_private	这条帖子不是公开内容。
unsupported_url	这不是 TikTok、Instagram 或 X 的帖子链接。
media_unavailable	平台未能返回媒体内容。
media_too_large	文件超过大小限制。
upload_invalid	无法读取上传的文件。
provider_error	上游服务出错，可以重试。
internal_error	我们这边出了问题，可以重试。

CLI

shell

export GARFUNKEL_API_KEY=gma_live_…

garfunkel submit urls.txt --category sports --dry-run   # free estimate
garfunkel submit urls.txt --category sports --wait      # run it
garfunkel results export job_… --format jsonl -o results.jsonl

# Whole accounts: counting is 2¢ per 20 posts (credited back when analyzed); you confirm the analysis
garfunkel submit --accounts accounts.txt --since 2025-01-01 --max-credits 50000

退出代码：0 成功，2 用法错误，3 身份验证失败，4 余额不足，5 已完成但有项目失败，6 超时。

MCP

通过 /api/mcp 使用 Streamable HTTP 远程连接 MCP，可通过 OAuth（在 Claude、ChatGPT 或 Cursor 中添加网址并授权）或 API 密钥进行身份验证。工具：estimate_job, submit_job, create_upload, confirm_job, list_job_posts, get_job, get_team, wait_for_job, list_results, get_result, list_accounts, get_account, analyze_comments, refresh_metrics, get_comments, search_results, export_results, chat_with_data, get_credit_balance, show_post, create_checkout。

mcp.json

{
  "mcpServers": {
    "garfunkel": {
      "type": "http",
      "url": "https://garfunkel.gar-ai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer gma_live_…"
      }
    }
  }
}