API, CLI ve MCP

Uygulamada yapabildiğiniz her şeyi kodunuzla ve ajanlarınızla da yapabilirsiniz: bağlantılar, dosyalar veya hesapların tamamını gönderin, etiketlerin hazırlanmasını bekleyin ve sonuçları alın. Üç farklı erişim yolu, tek bir sözleşme. İşler arka planda yürütülür, yazma işlemleri yinelendiğinde yeniden uygulanmaz ve maliyeti hem işlem öncesinde hem sonrasında görebilirsiniz.

Garfunkel’i ilk kez mi kullanıyorsunuz? Bir gönderinin nasıl analiz edildiğini görün.

Hızlı başlangıç

Uygulamada Ayarlar → Geliştiriciler bölümünden bir API anahtarı oluşturun, GARFUNKEL_API_KEY olarak ayarlayın ve ardından erişim yolunuzu seçin. MCP istemcileri anahtar yerine OAuth ile de oturum açabilir.

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

Kimlik doğrulama

API anahtarları bölümünden aldığınız, kuruluş kapsamındaki API anahtarını Authorization: Bearer gma_live_… olarak gönderin. CLI ve MCP, GARFUNKEL_API_KEY değişkenini okur. Her POST isteğinde bir Idempotency-Key kabul edilir; istek yinelenirse ilk yanıt döndürülür ve ücret ikinci kez alınmaz.

İş gönderme

İstek gönderdiğinizde hemen bir iş kimliği döner (202). priority için standard (daha uygun fiyatlı, dakikalar ile saatler arasında) veya fast seçin. Ücretsiz tahmin ve her öğe için doğrulama almak üzere dry_run: true ayarını kullanın.

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

Öğe durumları: queued → fetching → processing → succeeded | failed | canceled.

Hesap işleri

“@handle hesabının 2025-01-01 tarihinden sonraki tüm gönderileri.” Ekibinizin daha önce görmediği her 20 gönderi için sayım ücreti 2¢’dir. Tutar başta bekletilir ve gönderileri analiz ettikçe bakiyenize eklenir. Ardından iş, hesap başına posts_found, oldest_post_at, reached_since ve notices bilgileriyle awaiting_confirmation durumunda bekler (örneğin platform yalnızca daha ileri bir tarihten sonraki gönderileri döndürdüğünde). POST /jobs/{id}/confirm ile onaylayın veya otomatik onay için options.max_credits değerini ayarlayın.

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

Yüklemeler

Dosyalar doğrudan depolama alanına yüklenir; API üzerinden geçmez. 24 saat içinde bir işe eklenmeyen dosyalar silinir.

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.

Sonuçlar

Analiz edilmiş tek bir gönderi. Gömme vektörleri yalnızca ?include=embedding ile birlikte döndürülür. pacing, çekim algılamadan gelir (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": "…"
}

Uç noktalar

Uç nokta	İşlevi
POST /api/v1/jobs	URL'leri, dosyaları veya hesapları gönderir (ücretsiz tahmin için dry_run).
GET /api/v1/jobs/{id}	Durum, duruma göre sayılar, ayrılan / tahsil edilen / bakiyeye iade edilen tutarlar (sent), hesaplar ve bildirimler.
GET /api/v1/jobs/{id}/items	Sayfalanmış öğeler; ?status=failed ile filtreleyin.
POST /api/v1/jobs/{id}/confirm	Onay bekleyen hesap işi için tutarı ayırır.
POST /api/v1/jobs/{id}/cancel	Kuyruktaki öğeleri iptal eder; ayrılan tutar bakiyeye geri eklenir.
POST /api/v1/jobs/{id}/retry	Başarısız öğeleri yeniden dener (maliyet yeniden hesaplanır ve tutar yeniden ayrılır).
POST /api/v1/uploads	Kendi medyanız için önceden imzalanmış PUT isteği.
GET /api/v1/results	job_id, platform, tag, q ile filtreleyin.
POST /api/v1/results/search	Gömme vektörleri üzerinde anlamsal arama.
GET /api/v1/results/export	CSV veya JSONL biçiminde akış.
GET /api/v1/credits	Bakiye (sent + balance_usd), ayrılan tutar, paketler ve harcama ödülleri.
DELETE /api/v1/data	Kuruluşunuzla ilgili tüm verileri silin.

Hatalar

2xx olmayan tüm yanıtlar aynı yapıyı kullanır. Kodlar: 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 } }

Öğe hatası kodları sabittir ve ücretlendirilmez:

post_not_found	Bu gönderi artık mevcut değil.
post_private	Bu gönderi herkese açık değil.
unsupported_url	Bu bağlantı bir TikTok, Instagram veya X gönderisine ait değil.
media_unavailable	Platform medyayı sağlamadı.
media_too_large	Boyut sınırı aşıldı.
upload_invalid	Yüklenen dosya okunamadı.
provider_error	Üst hizmette hata oluştu; yeniden deneyebilirsiniz.
internal_error	Bizden kaynaklanan bir hata oluştu; yeniden deneyebilirsiniz.

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

Çıkış kodları: 0 başarılı, 2 kullanım hatası, 3 kimlik doğrulama hatası, 4 yetersiz bakiye, 5 bazı öğeler işlenemedi, 6 zaman aşımı.

MCP

Streamable HTTP üzerinden uzaktan MCP: /api/mcp. OAuth kullanmak için URL’yi Claude, ChatGPT veya Cursor’a ekleyip onaylayın; API anahtarı da kullanabilirsiniz. Araçlar: 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_…"
      }
    }
  }
}