مرکز توسعه‌دهندگان، API ترکیبی و سرور MCP فلای‌کراول

Existing applications built with the official firecrawl-py Python SDK or @mendable/firecrawl-js can target FlyCrawl directly by setting api_url="https://flycrawl.net/api/v1". Below is our verified endpoint and parameter support matrix tested via tests/test_firecrawl_compat.py:

# Python Example: Pre-Flight Estimation & Graceful Insufficient Credits Handling
import requests

res = requests.post("https://flycrawl.net/api/v1/crawl",
    headers={"Authorization": "Bearer fly_live_your_key"},
    json={"url": "https://target-site.com", "limit": 100, "dryRun": True}
)

if res.status_code == 200:
    data = res.json()
    print(f"Site requires {data['estimated_credits']} credits. Can afford: {data['can_afford']}")
    if data["can_afford"]:
        # Execute actual crawl:
        job = requests.post("https://flycrawl.net/api/v1/crawl",
            headers={"Authorization": "Bearer fly_live_your_key"},
            json={"url": "https://target-site.com", "limit": 100}
        ).json()
        print(f"Crawl job started: {job['id']}")
elif res.status_code == 402:
    err = res.json()
    print(f"Insufficient balance! Shortage: {err['shortage']} credits. Suggested max pages: {err['suggested_max_pages']}")

راهنمای مدیریت خطا و ضمانت صورت‌حساب عادلانه

در طراحی ایجنت‌های هوش مصنوعی و خزشگرهای سازمانی، مواجهه با خطاهای سرور مقصد اجتناب‌ناپذیر است. فلای‌کراول طبق قانون تضمین صورت‌حساب عادلانه عمل می‌کند: در صورت بروز خطای سرور مقصد، تایم‌اوت یا مسدودی، هیچ اعتباری از شما کسر نخواهد شد.

جدول کدهای خطای API و وضعیت کسر اعتبار

الگوی استاندارد بازتلاش در ایجنت‌ها

نحوه تنظیم کلاینت با بازتلاش تصادفی در صورت برخورد با ریت‌لیمیت یا تایم‌اوت:

from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception
import httpx

# Retry up to 3 times ONLY on 429 or 504 (Fair billing guarantees zero extra costs)
@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential_jitter(initial=1, max=5),
    retry=retry_if_exception(lambda e: isinstance(e, httpx.HTTPStatusError) and e.response.status_code in (429, 504))
)
def robust_scrape(url: str):
    with httpx.Client(base_url="https://api.flycrawl.net/v1") as client:
        res = client.post("/scrape", json={"url": url}, headers={"Authorization": "Bearer YOUR_KEY"})
        res.raise_for_status()
        return res.json()

معماری موتور جستجو، کیفیت و تازگی ایندکس وب

برخلاف موتورهای جستجوی سنتی که نتایج را آلوده به تبلیغات تجاری، لینک‌های بازاریابی و کلمات کلیدی اسپم برمی‌گردانند، اندپوینت /search فلای‌کراول اختصاصاً برای ایجنت‌های هوش مصنوعی مهندسی شده و صفحات منتخب را مستقیماً به مارک‌داون تمیز تبدیل می‌کند.

معماری دوگانه وکتور: امبدینگ‌های نورونی و پروجکشن لکزیکال سریع

فلای‌کراول یک معماری دوگانه و انعطاف‌پذیر برای تولید بردار ارائه می‌دهد: برای پروژه‌های RAG و جستجوی معنایی عمیق، از امبدینگ‌های استاندارد نورونی (مدل‌های text-embedding-3 با پشتیبانی از BYOK و کردیت سرور) استفاده می‌شود؛ و برای خوشه‌بندی سریع و حذف اسناد تکراری در حافظه با هزینه صفر، پروجکشن‌های لکزیکال فوق‌سریع در کمتر از ۱۰ میلی‌ثانیه محاسبه و تحویل داده می‌شوند.

🐍 پیاده‌سازی حرفه‌ای RAG: استخراج تمیز با فلای‌کراول و جستجوی استاندارد

استخراج مارک‌داون بدون نویز به همراه امبدینگ در یک درخواست HTTP و ایندکس در پایگاه داده برداری:

import httpx
from openai import OpenAI
from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct, Distance, VectorParams

qdrant = QdrantClient(url="http://localhost:6333")
qdrant.recreate_collection("tech_docs", vectors_config=VectorParams(size=1536, distance=Distance.COSINE))

# 1. INGESTION TIME: Extract Fit-Markdown + neural embeddings via FlyCrawl in 1 API call
res = httpx.post(
    "https://api.flycrawl.net/v1/scrape",
    headers={"Authorization": "Bearer fly_live_your_key"},
    json={
        "url": "https://example.com/docs",
        "formats": ["markdown", "vector"],
        "embedding_model": "text-embedding-3-small" # Neural embeddings (or "native" for lexical)
    }
).json()

doc_vector = res["data"]["vector"] # 1536-dim float array
qdrant.upsert("tech_docs", points=[PointStruct(id=1, vector=doc_vector, payload={"url": "https://example.com/docs"})])

# 2. QUERY TIME: Embed user question using standard OpenAI client
ai_client = OpenAI()
query_vector = ai_client.embeddings.create(
    model="text-embedding-3-small",
    input="How do I configure authentication?"
).data[0].embedding

# 3. Semantic cosine retrieval in vector database
search_results = qdrant.search("tech_docs", query_vector=query_vector, limit=3)
print(f"Top matched document: {search_results[0].payload['url']}")

گستره جغرافیایی پروکسی مسکونی و سقف خزش موازی

برای تضمین کیفیت خدمات و تاخیر قابل پیش‌بینی برای تمام تیم‌ها، فلای‌کراول چارچوب مشخصی برای شبکه پروکسی مسکونی و سقف خزش موازی تعریف کرده است:

نشست‌های ماندگار مرورگر و خزش صفحات خصوصی و نیازمند لاگین

صفحات پشت سد ورود، داشبوردهای کاربری و پرتال‌های سازمانی را بدون نیاز به ارسال مکرر نام‌کاربری و رمز عبور استخراج کنید. فلای‌کراول مراحل ورود خودکار را اجرا کرده، وضعیت احراز هویت (کوکی‌ها و LocalStorage) را با رمزنگاری پیشرفته AES-256-GCM ذخیره می‌کند. کافی است پارامتر session_id را در درخواست‌های بعدی ارسال کنید.

# Step 1: Initialize session with automated login actions
curl -X POST "https://api.flycrawl.net/v1/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com/login",
    "actions": [
      { "type": "write", "selector": "input[name=acct]", "text": "my_user" },
      { "type": "write", "selector": "input[name=pw]", "text": "secret_pass" },
      { "type": "click", "selector": "input[value=login]" },
      { "type": "wait", "milliseconds": 2000 }
    ],
    "ttl_hours": 168
  }'

# Response: { "success": true, "session_id": "sess_9f8a7b6c5d4e...", "expires_at": "..." }

# Step 2: Scrape private authenticated URLs using session_id
curl -X POST "https://api.flycrawl.net/v1/scrape" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com/threads?id=my_user",
    "session_id": "sess_9f8a7b6c5d4e..."
  }'

ایجنت خودمختار استخراج هدف‌محور از چندین وبسایت

تنها هدف کلی یا ساختار JSON مورد نظر را اعلام کنید. ایجنت هوشمند فلای‌کراول عبارات جستجوی بهینه را تدوین کرده، بهترین منابع وب را پیدا می‌کند، به طور همزمان صفحات را خزش کرده و داده‌ها را با انطباق دقیق بر ساختار شما سنتز می‌نماید. از استریم زنده وضعیت (SSE) به صورت پیش‌فرض پشتیبانی می‌شود.

# Python Example: Autonomous Agent with Target JSON Schema
import requests

payload = {
    "goal": "Compare pricing tiers, rate limits, and LLM features between Firecrawl and Spider",
    "schema": {
        "providers": [
            {
                "name": "string",
                "starting_price": "string",
                "concurrent_rate_limit": "string",
                "markdown_quality": "string",
                "unique_features": ["string"]
            }
        ]
    },
    "max_steps": 5
}

res = requests.post(
    "https://api.flycrawl.net/v1/agent",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json=payload
).json()

print("Agent Summary:", res["summary"])
print("Synthesized Data:", res["data"])
print("Sources Visited:", res["sources"])

مانیتورینگ تغییرات وبسایت و موتور تحلیل دیف متنی و مفهومی

تغییرات قیمت رقبا، موجودی انبار، قوانین و مقررات را در بازه‌های زمانی دلخواه پایش کنید. سیستم بر پایه هش SHA-256 تغییرات را رصد کرده و در صورتی که محتوا دست‌نخورده باشد، دقیقاً ۰ کردیت کسر می‌شود. در صورت تغییر، هوش مصنوعی خلاصه تحلیلی تفاوت‌ها را استخراج کرده و وب‌هوک با امضای امنیتی HMAC ارسال می‌کند.

# Create a Change Monitor on Pricing Table
curl -X POST "https://api.flycrawl.net/v1/monitor" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "selector": ".pricing-grid",
    "diff_mode": "semantic",
    "frequency": "daily",
    "webhook_url": "https://api.yourdomain.com/webhooks/pricing-change"
  }'

# Webhook payload dispatched upon detected change:
{
  "event": "monitor.change_detected",
  "monitor_id": "mon_4a3b2c1d...",
  "url": "https://example.com/pricing",
  "detected_at": "2026-10-26T12:00:00Z",
  "summary": "• Pro tier price increased from $49/mo to $59/mo.\n• Added 50,000 monthly credits.\n• Annual billing discount changed from 20% to 25%.",
  "diff": "--- previous\n+++ current\n- Pro: $49/mo\n+ Pro: $59/mo",
  "previous_hash": "a1b2c3...",
  "new_hash": "d4e5f6..."
}