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。

帳號工作

「從 2025-01-01 起，@handle 的每則貼文。」計算團隊尚未處理的新貼文，每 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

透過 Streamable HTTP 提供遠端 MCP，網址為 /api/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_…"
      }
    }
  }
}