API وCLI وMCP

يمكنك أنت أيضًا تنفيذ كل ما تفعله في التطبيق باستخدام الشيفرة والوكلاء: أرسل روابط أو ملفات أو حسابات كاملة، وانتظر تصنيف المنشورات، ثم اطّلع على النتائج. واجهة واحدة وثلاث طرق لاستخدامها. تُنفّذ المهام بشكل غير متزامن، ولا تكرّر طلبات الكتابة أثرها، ويمكنك معرفة التكلفة قبل التنفيذ وبعده.

هل تستخدم Garfunkel للمرة الأولى؟ تعرّف على كيفية تحليل المنشور.

البدء السريع

أنشئ مفتاح 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؛ وتُعيد الطلبات المكررة الاستجابة الأصلية من دون خصم المبلغ مرتين.

إرسال مهمة

يعيد الإرسال معرّف المهمة فورًا (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». تكلفة العدّ 2¢ لكل 20 منشورًا جديدًا على فريقك. تُحجز التكلفة مقدمًا وتُردّ إليك عند تحليل المنشورات؛ ثم تنتظر المهمة في 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

اتصال MCP عن بُعد عبر HTTP القابل للبث على /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_…"
      }
    }
  }
}