API, CLI และ MCP

ทุกอย่างที่ทำได้ในแอป คุณก็ทำผ่านโค้ดและเอเจนต์ได้เช่นกัน ไม่ว่าจะส่งลิงก์ ไฟล์ หรือทั้งบัญชี แล้วรอรับแท็กและดูผลลัพธ์ ใช้รูปแบบการเชื่อมต่อเดียวกันได้สามวิธี ระบบทำงานเบื้องหลัง คำสั่งที่ส่งซ้ำจะไม่ทำรายการซ้ำ และคุณดูค่าใช้จ่ายได้ทั้งก่อนและหลัง

เพิ่งรู้จัก Garfunkel ใช่ไหม ดูวิธีวิเคราะห์โพสต์

เริ่มต้นใช้งาน

สร้าง API key ในแอปที่ Settings → Developers แล้วตั้งค่าเป็น 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 key ที่ใช้ได้กับองค์กรนั้น จากหน้า API keys ส่วน 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": "…"
}

ปลายทาง API

ปลายทาง API	ทำอะไร
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 ที่ลงนามไว้ล่วงหน้าสำหรับอัปโหลดไฟล์สื่อของคุณ
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	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 key เครื่องมือ: 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_…"
      }
    }
  }
}