API هوش مصنوعی دیپ‌فا،
سازگار با OpenAI

POST /v1/messages

شکل API مسیجز Anthropic، برای مدل‌های Claude؛ همان مسیری که Claude Code با ANTHROPIC_BASE_URL برابر https://deepfa.ir/api صدا می‌زند. بدنه بی‌تغییر فرستاده می‌شود: system به‌صورت بلوک، cache_control، thinking و ابزارها، و هدرهای anthropic-beta و anthropic-version هم منتقل می‌شوند. استریم رویداد به رویداد و به همان ترتیب برمی‌گردد و خطاها به شکل خطای Anthropic است. شناسه‌های تاریخ‌دار مثل claude-haiku-4-5-20251001 و پسوند [1m] هم پذیرفته می‌شوند.

چند چیز برداشته می‌شود، چون هر کدام بیرون از نرخ توکن جدول قیمت هزینه دارد: speed (حالت سریع)، inference_geo و service_tier، و ابزارهای سمت سرور جست‌وجوی وب و اجرای کد که Anthropic به‌ازای هر بار استفاده حساب می‌کند. POST /v1/messages/count_tokens توکن‌های یک درخواست را بدون هزینه می‌شمارد. مدل‌های غیر Claude از /v1/chat/completions در دسترس‌اند.

POST /v1/responses

شکل API ریسپانسز OpenAI، برای مدل‌های OpenAI؛ تنها شکلی که Codex با آن کار می‌کند (wire_api = "responses"). آیتم‌های input، آیتم‌های استدلال با محتوای رمزشده‌شان، و ابزارهای function، custom و shell بی‌تغییر منتقل می‌شوند. پاسخی که ذخیره می‌شود (پیش‌فرض، مگر "store": false) سی روز نگه داشته می‌شود و previous_response_id آن فقط برای همان حساب کار می‌کند. پارامتر conversation پشتیبانی نمی‌شود.

برداشته می‌شود: service_tier، background و ابزارهای میزبانی‌شده‌ای که به‌ازای هر استفاده هزینه دارند (جست‌وجوی وب و فایل، code interpreter، ساخت تصویر، computer use و MCP راه دور).

نام مدل‌های بازنشسته

درخواستی که نام مدلی جایگزین‌شده را دارد، مثل gpt-5.6-luna، با مدل جانشین (gpt-6-luna) و به قیمت آن پاسخ داده می‌شود و صاحب کلید یک بار با ایمیل و اعلان پنل خبردار می‌شود. فهرست این نام‌ها در زبانهٔ مدل‌های صفحهٔ API است.

POST /v1/images/generations — تصویرها به‌صورت b64_json (PNG با base64) برمی‌گردند و فقط برای تصویرهایی که واقعاً ساخته شده‌اند هزینه کم می‌شود.

{
  "model": "flux-schnell",
  "prompt": "A lighthouse at dawn, watercolour",
  "n": 2,
  "size": "1536x1024"
}

POST /v1/images/edits

تصویر به تصویر، به شکل multipart/form-data مثل OpenAI: یک تا چهار تصویر به‌همراه توضیح می‌فرستید و تصویر تازه به‌صورت b64_json برمی‌گردد. قیمت هر تصویر همان قیمت مدل است؛ در مدل‌هایی که سرویس‌دهنده برای هر تصویر ورودی هزینه می‌گیرد، هر تصویر ورودی مبلغ credits_per_input_image را در GET /v1/models اضافه می‌کند.

curl https://deepfa.ir/api/v1/images/edits \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -F model=flux-3 \
  -F "image[]=@product.png" \
  -F "prompt=Place this bottle on a marble counter in soft morning light"

POST /v1/audio/speech

فایل صوتی را مستقیم برمی‌گرداند و به‌ازای هر کاراکتر هزینه دارد.

POST /v1/audio/transcriptions

به شکل multipart/form-data؛ به‌ازای هر دقیقهٔ شروع‌شده هزینه دارد.

ساخت ویدیو چند دقیقه طول می‌کشد، پس یک «کار» است: POST /v1/videos کار را شروع می‌کند و بی‌درنگ شناسه‌اش را با وضعیت queued برمی‌گرداند؛ GET /v1/videos/{id} را هر چند ثانیه بخوانید تا وضعیت از in_progress به completed (با url فایل) یا failed برسد؛ GET /v1/videos/{id}/content به فایل آماده هدایت می‌کند (کد ۳۰۲) و اگر آماده نباشد ۴۰۹ می‌دهد. هزینه هنگام پذیرش کار کم می‌شود و اگر کار ناموفق شود، کامل برمی‌گردد.

مدل‌ها و مدت‌های مجاز

curl https://deepfa.ir/api/v1/videos \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "grok-imagine-15",
  "prompt": "A paper boat sailing down a rainy street",
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'

{
  "id": "t_48213",
  "object": "video",
  "model": "grok-imagine-15",
  "kind": "text_to_video",
  "status": "queued",
  "seconds": 5,
  "created_at": 1790443124
}

پادکست یک «کار» است، مثل ویدیو: POST /v1/podcasts سناریو را می‌گیرد و بی‌درنگ شناسه‌ای مثل p_123 برمی‌گرداند؛ با GET /v1/podcasts/{id} وضعیت را بپرسید تا completed شود و با GET /v1/podcasts/{id}/content فایل صوتی را بگیرید (?what=transcript متن و ?what=srt زیرنویس). صدا با مدل gemini-3.8-flash-lite-tts ساخته می‌شود؛ هزینه فقط یک‌بار و پس از ساخت کامل، به‌اندازهٔ کاراکترهای خوانده‌شده و با همان نرخ /v1/audio/speech برای این مدل است، و اگر ساخت ناموفق باشد چیزی کم نمی‌شود. نوشتن سناریو با خود شماست (برای نوشتن آن از /v1/chat/completions استفاده کنید).

حداکثر ۱۲٬۰۰۰ کاراکتر در هر پادکست (حدود بیست دقیقه) و سه پادکستِ هم‌زمان برای هر حساب. پادکست‌هایی که با API ساخته شوند در فهرست ابزار «پادکست هوش مصنوعی» هم دیده می‌شوند.

curl https://deepfa.ir/api/v1/podcasts \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"en","voices":["Kore","Puck"],"turns":[{"speaker":1,"text":"Hi everyone, welcome! "},{"speaker":2,"text":"Glad to be here.","style":"warmly"}]}'

{"id":"p_123","object":"podcast","model":"gemini-3.8-flash-lite-tts","status":"queued","progress":0}

مدل سه‌بعدی هم یک «کار» است: POST /v1/3d یک عکس (image_url)، چند عکس از یک چیز از زاویه‌های مختلف (image_urls) یا یک توضیح (prompt) می‌گیرد و شناسه‌ای مثل 3d_123 برمی‌گرداند؛ GET /v1/3d/{id} را بپرسید تا completed شود و فایل را از GET /v1/3d/{id}/content بگیرید (?format=glb پیش‌فرض؛ obj، fbx، usdz یا stl اگر موتور ساخته باشد، در فهرست files). ساخت معمولاً یک تا چند دقیقه طول می‌کشد. هزینه وقتی سرویس‌دهنده کار را بپذیرد کم می‌شود و اگر ساخت ناموفق باشد به اعتبار API برمی‌گردد. مدل‌هایی که با API ساخته شوند در «استودیو سه‌بعدی» حساب شما هم دیده می‌شوند.

قیمت‌ها با تنظیمات پیش‌فرض هر مدل است؛ گزینه‌هایی مثل texture: "hd"، hd: true یا کاراکتر متحرک به آن اضافه می‌کنند و هزینهٔ دقیق هر درخواست در هدر x-deepfa-credits برمی‌گردد.

curl https://deepfa.ir/api/v1/3d \
  -H "Authorization: Bearer $DEEPFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tripo-h3.1","image_url":"https://example.com/chair.jpg","texture":"hd"}'

{"id":"3d_123","object":"3d_model","model":"tripo-h3.1","status":"completed",
 "files":[{"format":"glb","label":"GLB: web, AR and most 3D apps","url":"https://deepfa.ir/api/v1/3d/3d_123/content?format=glb"}],
 "preview_image_url":"..."}

برای هزاران درخواست، به شکل Batch API در OpenAI و با همان کتابخانه‌ها: درخواست‌ها را در یک فایل JSONL بنویسید (هر خط یک درخواست)، با POST /v1/files و purpose=batch بالا بفرستید، با POST /v1/batches اجرا را شروع کنید، GET /v1/batches/{id} را بپرسید تا وضعیت completed شود و پاسخ‌ها را از GET /v1/files/{output_file_id}/content بگیرید. درخواست‌ها ظرف ۲۴ ساعت در پس‌زمینه اجرا می‌شوند، بدون محدودیت سرعت کلید، و هر کدام دقیقاً به قیمت همان درخواست زنده و با سقف‌های روزانه و ماهانهٔ کلید حساب می‌شود.

{"custom_id": "news-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-6-luna", "messages": [{"role": "user", "content": "..."}]}}
{"custom_id": "news-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-6-luna", "messages": [{"role": "user", "content": "..."}]}}

curl https://deepfa.ir/api/v1/files -H "Authorization: Bearer $DEEPFA_API_KEY" -F purpose=batch -F file=@requests.jsonl
curl https://deepfa.ir/api/v1/batches -H "Authorization: Bearer $DEEPFA_API_KEY" -H "Content-Type: application/json" \
  -d '{"input_file_id": "file-...", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'

به‌جای پرسیدن مداوم وضعیت، در زبانهٔ «اتصال» صفحهٔ API یک آدرس https بدهید. با پایان هر کار طولانی یک رویداد به آن ارسال می‌شود و اگر سرور شما با 2xx پاسخ ندهد، تا حدود یک روز دوباره تلاش می‌شود (پس از ۱، ۵ و ۳۰ دقیقه، ۲، ۶ و ۱۵ ساعت). بدنهٔ رویداد فقط شناسهٔ کار را دارد؛ نتیجه را با کلید خودتان بخوانید.

{"id": "evt_...", "object": "event", "type": "video.completed", "created_at": 1793000000,
 "data": {"id": "t_123", "object": "video", "status": "completed"}}

بررسی امضا

هر ارسال سه هدر استاندارد Standard Webhooks دارد که Webhookهای خود OpenAI هم به کار می‌برند: webhook-id، webhook-timestamp و webhook-signature (به شکل v1, و سپس HMAC-SHA256 رشتهٔ «id.timestamp.body» با بایت‌های کلید امضا، به base64). کلید امضا (whsec_...) در همان زبانهٔ «اتصال» است؛ کتابخانه‌های Standard Webhooks و تابع webhooks.unwrap در SDK رسمی OpenAI آن را بررسی می‌کنند.

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

event = Webhook("whsec_...").verify(request_body, request_headers)  # raises if forged

GET /v1/models

فقط مدل‌هایی را برمی‌گرداند که پلن و کلید شما اجازه می‌دهند، هر کدام با شیء pricing به اعتبار. در مدل‌های متنی: input_per_million_tokens، output_per_million_tokens، و در صورت وجود cached_input_per_million_tokens و cache_write_per_million_tokens. در مدل‌های دیگر: credits به‌ازای credits_per (image، character، minute، video، second یا model)؛ در مدل سه‌بعدی، کمترین قیمت با from و ورودی‌ها با inputs و max_images آمده‌اند؛ در ویدیو، seconds و resolution هم کلیپی را نشان می‌دهند که قیمتش آمده است. همیشه همان قیمتی است که واقعاً کسر می‌شود.

GET /v1/balance

موجودی‌ای که همین کلید می‌تواند خرج کند، بدون هزینه. available اعتبار حساب است که API به آن دسترسی دارد و pockets آن را به ترتیب خرج نشان می‌دهد: اعتبار API، اعتبار پلن، اعتبار پیش‌پرداخت. key سقف‌های روزانه و ماهانهٔ همین کلید را با مقدار خرج‌شده نشان می‌دهد و spendable چیزی است که کلید همین حالا می‌تواند خرج کند، یعنی موجودی محدود به نزدیک‌ترین سقف. در حساب نامحدود unlimited برابر true و available برابر null است. برای عضو تیمی که صاحب تیم API را برایش باز کرده، pockets.team سهم او از اعتبار تیم (در سقف ماهانه‌اش) است و در available حساب می‌شود.

curl https://deepfa.ir/api/v1/balance -H "Authorization: Bearer $DEEPFA_API_KEY"

{
  "object": "balance",
  "unit": "credits",
  "unlimited": false,
  "available": 6500,
  "pockets": {"api": 5000, "plan": 1200, "prepaid": 300},
  "key": {
    "name": "production",
    "rpm_limit": 60,
    "daily":   {"limit": 100,  "spent": 30, "remaining": 70},
    "monthly": {"limit": null, "spent": 30, "remaining": null}
  },
  "spendable": 70
}

هر خطا به شکل استاندارد OpenAI برمی‌گردد و code همان type است؛ param نام فیلدی است که مشکل دارد. در /v1/messages خطا به شکل Anthropic برمی‌گردد.

{
  "error": {
    "message": "The model \"gpt-9\" is not available.",
    "type": "model_not_found",
    "param": "model",
    "code": "model_not_found"
  }
}

محدودیت‌ها

• تعداد درخواست در دقیقه برای هر کلید: پیش‌فرض ۶۰؛ هنگام ساخت یا ویرایش کلید در پنل می‌توانید آن را از ۱ تا ۶۰۰۰ بگذارید. بیش از آن، ۴۲۹ با هدر Retry-After.
• سقف اعتبار روزانه و ماهانه برای هر کلید، اختیاری، در پنل؛ مقدار باقی‌مانده‌اش را GET /v1/balance نشان می‌دهد.
• برای هر کلید، اختیاری: نشانی‌های IP مجاز (IPv4، IPv6 یا بازهٔ CIDR)، گروه مسیرهای مجاز، تاریخ پایان، و خاموش کردن موقت.
• حداکثر سه اجرای ایجنت هم‌زمان برای هر حساب.
• فایل رونوشت حداکثر ۲۵ مگابایت؛ متن گفتار حداکثر ۴۰۹۶ کاراکتر؛ تصویر حداکثر ۱۰ عدد در هر درخواست؛ ویرایش ویدیو 1 تا 120 ثانیه.
• هزینهٔ هر درخواست در هدر x-deepfa-credits و شناسهٔ آن در x-deepfa-request-id برمی‌گردد؛ این شناسه را هنگام تماس با پشتیبانی بفرستید.

هدرهای اختیاری

• X-DeepFA-Tag: برچسبی تا ۶۴ کاراکتر برای هر درخواست (پروژه، بخش، یکی از مشتریانتان)؛ صفحهٔ مصرف و فایل Excel مصرف را به تفکیک آن نشان می‌دهند. برچسب فارسی را درصد-کد (URL-encode) کنید، چون بیشتر کتابخانه‌ها حروف غیرلاتین را در هدر نمی‌پذیرند.
• Idempotency-Key: اگر همان درخواست را با همان کلید تا یک روز دوباره بفرستید (مثلاً پس از قطع اتصال)، پاسخ اول با هدر Idempotent-Replayed: true برمی‌گردد و درخواست دوباره اجرا و حساب نمی‌شود. پاسخ‌های جریانی (stream) بازپخش نمی‌شوند؛ کلیدشان فقط جلوی اجرای دوباره را می‌گیرد.

برای ابزارها و پایش

• توصیف کامل API به شکل OpenAPI 3.1، برای وارد کردن در Postman یا Insomnia یا ساخت کلاینت: /api/openapi.json
• وضعیت لحظه‌ای و نود روز اخیر هر بخش API: صفحهٔ وضعیت و برای پایش خودکار /api/status.json