API, CLI, dan MCP

Semua yang bisa kamu lakukan di aplikasi juga bisa dilakukan lewat kode dan agen: kirim tautan, unggahan, atau seluruh akun, tunggu sampai post diberi tag, lalu lihat hasilnya. Satu kontrak dengan tiga cara untuk mengaksesnya. Tugas berjalan secara asinkron, permintaan tulis yang diulang tidak diproses dua kali, dan kamu bisa melihat biayanya sebelum dan sesudah.

Baru mengenal Garfunkel? Lihat cara sebuah post dianalisis.

Mulai cepat

Buat kunci API di aplikasi lewat Pengaturan → Developer, atur sebagai GARFUNKEL_API_KEY, lalu pilih cara yang ingin kamu gunakan. Klien MCP juga bisa masuk dengan OAuth tanpa kunci.

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

Autentikasi

Kirim Authorization: Bearer gma_live_… — kunci API yang berlaku untuk satu organisasi dari Kunci API. CLI dan MCP membaca GARFUNKEL_API_KEY. Setiap POST menerima Idempotency-Key; jika permintaan dikirim ulang, respons awal akan dikembalikan dan kamu tidak akan dikenai biaya dua kali.

Kirim tugas

Saat dikirim, tugas langsung mendapat ID (202). priority bisa berupa standard (lebih murah, beberapa menit hingga beberapa jam) atau fast. Atur dry_run: true untuk melihat perkiraan gratis sekaligus memvalidasi tiap item.

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
  }'

Status item: queued → fetching → processing → succeeded | failed | canceled.

Tugas akun

“Setiap post dari @handle sejak 2025-01-01.” Biaya penghitungan adalah 2¢ per 20 post yang baru bagi tim kamu. Biaya ditahan di awal dan dikembalikan saat post dianalisis. Setelah itu, tugas menunggu di awaiting_confirmation dengan informasi per akun: posts_found, oldest_post_at, reached_since, dan notices (misalnya saat platform hanya menampilkan post sejak tanggal yang lebih baru). Konfirmasi dengan POST /jobs/{id}/confirm, atau atur options.max_credits untuk konfirmasi otomatis.

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 }
}

Unggahan

Data dikirim langsung ke penyimpanan, bukan melalui API. Unggahan yang tidak dilampirkan ke tugas dalam 24 jam akan dihapus.

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.

Hasil

Satu post yang sudah dianalisis. Vektor embedding hanya dikembalikan jika kamu menyertakan ?include=embedding. pacing berasal dari deteksi adegan (beta).

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": "…"
}

Endpoint

Endpoint	Fungsi
POST /api/v1/jobs	Kirim URL, file, atau akun (dry_run untuk mendapat perkiraan gratis).
GET /api/v1/jobs/{id}	Status, jumlah per status, nominal (sen) yang disisihkan / ditagihkan / dikembalikan, akun, dan pemberitahuan.
GET /api/v1/jobs/{id}/items	Item berpaginasi; filter dengan ?status=failed.
POST /api/v1/jobs/{id}/confirm	Sisihkan biaya untuk tugas akun yang menunggu konfirmasi.
POST /api/v1/jobs/{id}/cancel	Batalkan item yang mengantre; dana yang disisihkan akan dikembalikan ke saldo.
POST /api/v1/jobs/{id}/retry	Coba lagi item yang gagal (biayanya dihitung ulang dan dana disisihkan kembali).
POST /api/v1/uploads	PUT dengan URL pratinanda untuk media milikmu.
GET /api/v1/results	Filter dengan job_id, platform, tag, q.
POST /api/v1/results/search	Pencarian semantik pada embedding.
GET /api/v1/results/export	CSV atau JSONL yang dialirkan.
GET /api/v1/credits	Saldo (sen + balance_usd), saldo tertahan, paket isi saldo, bonus pemakaian.
DELETE /api/v1/data	Hapus semua data organisasi kamu.

Error

Semua respons non-2xx memakai format yang sama. Kode: 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 } }

Kode kegagalan item bersifat tetap dan tidak dikenai biaya:

post_not_found	Post ini sudah tidak ada.
post_private	Post ini tidak bersifat publik.
unsupported_url	URL ini bukan URL post TikTok, Instagram, atau X.
media_unavailable	Platform tidak menyediakan medianya.
media_too_large	Ukuran media melebihi batas.
upload_invalid	File yang diunggah tidak bisa dibaca.
provider_error	Terjadi gangguan pada layanan penyedia. Bisa dicoba lagi.
internal_error	Terjadi gangguan di pihak kami. Bisa dicoba lagi.

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

Kode keluar: 0 berhasil, 2 penggunaan, 3 autentikasi, 4 saldo tidak cukup, 5 selesai dengan beberapa item gagal, 6 waktu habis.

MCP

MCP jarak jauh melalui Streamable HTTP di /api/mcp dengan OAuth (tambahkan URL di Claude, ChatGPT, atau Cursor lalu setujui) atau kunci API. Alat: 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_…"
      }
    }
  }
}