API、CLI、MCP

アプリでできることは、コードやエージェントからも実行できます。リンク、アップロードしたファイル、アカウント全体を送信し、タグ付けの完了を待って結果を確認できます。共通の仕様を3つの方法で利用できます。ジョブは非同期で処理され、書き込みを繰り返しても重複せず、処理の前後に費用を確認できます。

Garfunkelを初めてお使いですか？投稿の分析方法を見る。

クイックスタート

アプリの設定 → 開発者向けで API キーを作成し、GARFUNKEL_API_KEY に設定して、利用方法を選びます。MCP クライアントは API キーの代わりに 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

認証

API キーで発行した組織単位の API キーを、Authorization: Bearer gma_live_… に設定して送信します。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.

結果

解析済みの投稿1件分の結果です。埋め込みベクトルは ?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	URL、アップロードしたファイル、アカウントを送信します（無料見積もりには 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 で直接アップロードするための署名付き URL を取得します。
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の投稿URLではありません。
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

OAuth（Claude、ChatGPT、CursorにURLを追加して承認）またはAPIキーを使い、/api/mcpでStreamable HTTP経由のリモートMCPに接続します。ツール：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_…"
      }
    }
  }
}