Перейти до вмісту
Garfunkel by GAR AI

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Підписаний URL для 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 через Streamable HTTP за адресою /api/mcp з OAuth (додайте URL у 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_…"
      }
    }
  }
}