{"openapi":"3.1.0","info":{"title":"API هوش مصنوعی نِت اَرز","version":"1.0.0","description":"یک نشانی و یک کلید برای مدل‌های OpenAI، Google Gemini، DeepSeek، Claude، Grok، Llama، Qwen، Mistral و بسیاری مدل دیگر؛ بخشی مستقیم از خود سازنده و بقیه از راه OpenRouter. فهرست به‌روز مدل‌ها در `GET /models` است. اعتبار دلاری است و با تومان خریده می‌شود.\n\n**سازگار با OpenAI:** کافی است در SDK رسمی OpenAI مقدار `base_url` را روی `https://netarz.ir/api/ai/v1` بگذارید و کلید پروژهٔ نِت اَرز را به‌جای کلید OpenAI استفاده کنید. هیچ تغییر دیگری لازم نیست.\n\n**احراز هویت:** `Authorization: Bearer sk-ntz-v1-…` (کلید را از پنل کاربری ← «API هوش مصنوعی» ← پروژه بسازید).\n\n**صورت‌حساب:** هر درخواست بر اساس مصرف واقعی (توکن / تصویر / دقیقه / کاراکتر) از اعتبار دلاری حساب کسر می‌شود. درخواستی که پیش از تولید پاسخ با خطای ارائه‌دهنده تمام شود، هزینه‌ای ندارد. قیمت هر مدل در `GET /models` منتشر می‌شود.\n\n**محدودیت‌ها:** به‌طور پیش‌فرض ۶۰ درخواست در دقیقه به‌ازای هر کلید و ۸ درخواست همزمان به‌ازای هر حساب (قابل تغییر از پنل). حداکثر بدنهٔ درخواست ۴ مگابایت.","contact":{"name":"پشتیبانی نِت اَرز","url":"https://netarz.ir"}},"servers":[{"url":"https://netarz.ir/api/ai/v1","description":"سرور اصلی (base_url)"},{"url":"https://ir.gisoo.pro/api/v1","description":"نشانی ویژهٔ ایران؛ برای سرورها و کاربران داخل ایران"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"مدل‌ها","description":"فهرست و قیمت مدل‌ها (بدون نیاز به کلید)"},{"name":"متن و گفت‌وگو","description":"Chat Completions / Responses / Completions"},{"name":"امبدینگ","description":"بردارسازی متن برای جستجوی معنایی و RAG"},{"name":"تصویر","description":"تولید تصویر"},{"name":"ویدیو","description":"ساخت ویدیو با Sora — کار ناهمگام: ساخت، پیگیری، دریافت فایل"},{"name":"موسیقی","description":"ساخت قطعهٔ موسیقی با Lyria 3"},{"name":"صدا","description":"گفتار به متن، ترجمهٔ صوت، متن به گفتار"},{"name":"پایش محتوا","description":"Moderations"},{"name":"حساب و مصرف","description":"موجودی، محدودیت‌ها و گزارش مصرف"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"کلید پروژه: sk-ntz-v1-…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","example":"اعتبار کافی نیست."},"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","insufficient_quota","rate_limit_error","upstream_error","service_unavailable"]},"code":{"type":"string","nullable":true,"example":"insufficient_credit"},"param":{"type":"string","nullable":true}}}}},"Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","example":42},"completion_tokens":{"type":"integer","example":128},"total_tokens":{"type":"integer","example":170},"prompt_tokens_details":{"type":"object","properties":{"cached_tokens":{"type":"integer"}}},"completion_tokens_details":{"type":"object","properties":{"reasoning_tokens":{"type":"integer"}}}}},"Message":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image_url"]},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}}}}}}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object"}}}},"Model":{"type":"object","properties":{"id":{"type":"string","example":"gpt-4o-mini","description":"شناسه‌ای که در فیلد model می‌فرستید"},"object":{"type":"string","example":"model"},"owned_by":{"type":"string","example":"openai","description":"ارائه‌دهنده"},"name":{"type":"string","example":"GPT-4o mini"},"type":{"type":"string","enum":["chat","embedding","image","audio","moderation"]},"context_length":{"type":"integer","nullable":true,"example":128000},"max_output_tokens":{"type":"integer","nullable":true},"capabilities":{"type":"object","example":{"vision":true,"tools":true,"json":true,"streaming":true}},"is_free":{"type":"boolean","description":"true یعنی قیمت این مدل صفر است؛ سقف روزانهٔ درخواست‌های رایگان روی آن اعمال می‌شود."},"pricing":{"type":"object","description":"قیمت به دلار: به‌ازای هر ۱ میلیون توکن مگر آنکه نام کلید چیز دیگری بگوید","example":{"input_per_million":"0.225000","output_per_million":"0.900000","cached_input_per_million":"0.112500"}},"pricing_toman":{"type":"object","description":"همان قیمت‌ها به تومان (نرخ روز)"}}},"ChatRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","example":"gpt-4o-mini"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"stream":{"type":"boolean","default":false,"description":"پاسخ به‌صورت Server-Sent Events (همان قالب OpenAI)"},"temperature":{"type":"number","example":0.7},"top_p":{"type":"number"},"max_tokens":{"type":"integer","example":1024,"description":"سقف توکن خروجی — تعیین آن مبلغ رزرو (hold) را کم می‌کند"},"max_completion_tokens":{"type":"integer"},"n":{"type":"integer","default":1,"maximum":4},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"response_format":{"type":"object","example":{"type":"json_object"}},"tools":{"type":"array","items":{"type":"object"}},"tool_choice":{"oneOf":[{"type":"string"},{"type":"object"}]},"reasoning_effort":{"type":"string","enum":["low","medium","high"],"description":"برای مدل‌های استدلالی (در Claude به بودجهٔ thinking تبدیل می‌شود)"},"user":{"type":"string","description":"شناسهٔ کاربر نهایی شما (اختیاری)"}}},"ChatResponse":{"type":"object","properties":{"id":{"type":"string","example":"req_9f2c1e0b7a6d4c3f8e1a2b3c"},"object":{"type":"string","example":"chat.completion"},"created":{"type":"integer"},"model":{"type":"string","example":"gpt-4o-mini"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/Message"},"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter"]}}}},"usage":{"$ref":"#/components/schemas/Usage"}}}}},"paths":{"/models":{"get":{"tags":["مدل‌ها"],"summary":"فهرست مدل‌ها و قیمت‌ها","security":[],"description":"همهٔ مدل‌های قابل فروش با قیمت دلاری و تومانی. با `?type=chat|embedding|image|audio|moderation` فیلتر کنید.","parameters":[{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"موفق","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}}}}},"/models/{id}":{"get":{"tags":["مدل‌ها"],"summary":"جزئیات یک مدل","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"gpt-4o-mini"}],"responses":{"200":{"description":"موفق","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chat/completions":{"post":{"tags":["متن و گفت‌وگو"],"summary":"Chat Completions (اصلی‌ترین endpoint)","description":"سازگار با OpenAI. برای Claude، Gemini، DeepSeek، Grok و مدل‌های OpenRouter هم همین endpoint را با همان بدنه صدا بزنید؛ ترجمه به پروتکل هر ارائه‌دهنده در سمت نِت اَرز انجام می‌شود.\n\n**استریم:** با `stream: true` رویدادهای `data: {...}` و در پایان `data: [DONE]` دریافت می‌کنید؛ آخرین رویداد شامل `usage` است.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"example":{"model":"gpt-4o-mini","messages":[{"role":"system","content":"تو دستیار فارسی‌زبان فروشگاه ما هستی."},{"role":"user","content":"سلام! یک شعار کوتاه برای فروشگاه لوازم ورزشی بنویس."}],"temperature":0.8,"max_tokens":200}}}},"responses":{"200":{"description":"موفق","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}},"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"id\":\"req_…\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"سلام\"}}]}\n\ndata: [DONE]"}}},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/responses":{"post":{"tags":["متن و گفت‌وگو"],"summary":"Responses API (OpenAI)","description":"عبور مستقیم Responses API برای مدل‌های OpenAI؛ ابزارهای داخلی مثل `web_search` هم کار می‌کنند (هزینهٔ هر فراخوانی ابزار به صورت‌حساب اضافه می‌شود).","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"gpt-4.1-mini","input":"نرخ امروز دلار را جستجو کن و خلاصه بگو.","tools":[{"type":"web_search"}]}}}},"responses":{"200":{"description":"موفق"},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/completions":{"post":{"tags":["متن و گفت‌وگو"],"summary":"Completions (قدیمی)","description":"برای سازگاری با ابزارهای قدیمی؛ `prompt` به یک پیام کاربر تبدیل می‌شود.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"gpt-4o-mini","prompt":"یک جملهٔ انگیزشی بنویس.","max_tokens":60}}}},"responses":{"200":{"description":"موفق"},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/embeddings":{"post":{"tags":["امبدینگ"],"summary":"Embeddings","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"text-embedding-3-small","input":["خرید اکانت چت‌جی‌پی‌تی","اشتراک کلود"]}}}},"responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.0123,-0.0456]}],"model":"text-embedding-3-small","usage":{"prompt_tokens":12,"total_tokens":12}}}}},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/generations":{"post":{"tags":["تصویر"],"summary":"تولید تصویر","description":"دو خانواده: GPT Image اوپن‌ای‌آی و Nano Banana گوگل (gemini-3-pro-image، gemini-3.1-flash-image، gemini-3.1-flash-lite-image). هر دو توکنی قیمت می‌خورند و خروجی همیشه base64 است. GPT Image: اندازه‌های 1024x1024، 1024x1536، 1536x1024. Nano Banana: `size` فقط قاب را تعیین می‌کند (نزدیک‌ترین نسبت؛ یا `aspect_ratio` مثل 16:9)، وضوح با `quality` = 1K | 2K | 4K (پیش‌فرض 1K)، تا چهار تصویر مرجع در `image` به‌صورت data URL، خروجی JPEG.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"gpt-image-1","prompt":"لوگوی مینیمال یک کافه با رنگ طلایی","size":"1024x1024","quality":"medium","n":1}}}},"responses":{"200":{"description":"موفق"},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos":{"post":{"tags":["ویدیو"],"summary":"ساخت ویدیو (کار ناهمگام) — Sora و Veo","description":"رندر یک تا چند دقیقه طول می‌کشد، پس این مسیر فایل نمی‌دهد: یک «کار» با شناسهٔ `vid_…` برمی‌گرداند. وضعیتش را از GET /videos/{id} بپرسید و وقتی `completed` شد فایل را از GET /videos/{id}/content بگیرید. هزینه به‌ازای هر ثانیهٔ ویدیو است و همان لحظهٔ پذیرش کسر می‌شود؛ رندر ناموفق خودکار برگشت می‌خورد.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"sora-2","prompt":"نمای هوایی از جادهٔ کوهستانی در مه صبحگاهی","seconds":"8","size":"1280x720"}}}},"responses":{"200":{"description":"کار پذیرفته شد","content":{"application/json":{"example":{"id":"vid_9f2c4a1b7e5d3c8a0b6f1e2d","object":"video","created_at":1790108108,"completed_at":null,"expires_at":null,"model":"sora-2","status":"queued","progress":0,"seconds":"8","size":"1280x720","usd":"1.120000","refunded":false,"error":null}}}},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["ویدیو"],"summary":"فهرست کارهای این پروژه","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"موفق"},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}":{"get":{"tags":["ویدیو"],"summary":"وضعیت یک رندر","description":"`status` یکی از queued | in_progress | completed | failed است و `progress` درصد پیشرفت. هر چند ثانیه یک‌بار بپرسید.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"vid_9f2c4a1b7e5d3c8a0b6f1e2d"}],"responses":{"200":{"description":"موفق"},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ویدیو"],"summary":"لغو رندر","description":"رندری که هنوز تحویل نشده باشد لغو و هزینه‌اش برگردانده می‌شود.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"موفق"},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}/content":{"get":{"tags":["ویدیو"],"summary":"دریافت فایل ویدیو","description":"فایل MP4. با `variant=thumbnail` تصویر بندانگشتی و با `variant=spritesheet` نوار فریم‌ها (فقط Sora؛ Veo ندارد و ۴۰۴ می‌دهد). فایل تنها ۴۸ ساعت در دسترس است.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"variant","in":"query","schema":{"type":"string","enum":["video","thumbnail","spritesheet"]}}],"responses":{"200":{"description":"فایل ویدیو","content":{"video/mp4":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/music":{"post":{"tags":["موسیقی"],"summary":"ساخت موسیقی","description":"یک قطعهٔ کامل MP3 در قالب base64. قیمت به‌ازای هر کلیپ یا آهنگ است، نه به‌ازای توکن. مدل‌های موسیقی را به /chat/completions نفرستید.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"openrouter/google/lyria-3-clip-preview","prompt":"قطعهٔ آرام پیانو با تمپوی کند، بدون کلام"}}}},"responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"object":"music.generation","model":"openrouter/google/lyria-3-clip-preview","text":"<instrumental>","data":[{"b64_json":"SUQzAwAAAAAvMkdFT0IA…","format":"mp3","bytes":744608}]}}}},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/transcriptions":{"post":{"tags":["صدا"],"summary":"گفتار به متن","description":"multipart/form-data با فیلد `file` (حداکثر ۲۵ مگابایت) و `model`. فرمت خروجی: json | text | srt | vtt | verbose_json (و diarized_json برای gemini-3.5-transcribe). `language=fa` دقت را بالا می‌برد. در gemini-3.5-transcribe، `diarize=true` گوینده‌ها را جدا می‌کند و `prompt` واژه‌نامهٔ اختصاصی (با ویرگول جدا) است.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string","example":"whisper-1"},"language":{"type":"string","example":"fa"},"response_format":{"type":"string","enum":["json","text","srt","vtt","verbose_json","diarized_json"]},"prompt":{"type":"string"},"diarize":{"type":"boolean","description":"فقط gemini-3.5-transcribe"}}}}}},"responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"text":"سلام، این یک تست است."}}}},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/translations":{"post":{"tags":["صدا"],"summary":"ترجمهٔ صوت به انگلیسی","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string","example":"whisper-1"}}}}}},"responses":{"200":{"description":"موفق"},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/speech":{"post":{"tags":["صدا"],"summary":"متن به گفتار","description":"خروجی باینری صوت (mp3 پیش‌فرض). مدل‌های OpenAI بر اساس تعداد کاراکتر و مدل‌های Gemini (gemini-3.8-flash-tts، gemini-3.8-flash-lite-tts) بر اساس توکن صدای ساخته‌شده قیمت می‌خورند. در Gemini: ۳۰ صدا (مثل Kore و Sulafat)، `instructions` لحن گفتار جدا از متن، `speakers` برای گفت‌وگوی دو نفره، حداکثر ۳٬۰۰۰ کاراکتر.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"tts-1","input":"به نِت اَرز خوش آمدید.","voice":"alloy","response_format":"mp3"}}}},"responses":{"200":{"description":"فایل صوتی","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/moderations":{"post":{"tags":["پایش محتوا"],"summary":"Moderations (فعلاً مدلی ندارد)","description":"قالب سازگار با OpenAI Moderations. در حال حاضر هیچ مدلی از خانوادهٔ پایش محتوا روی درگاه فعال نیست، پس این مسیر ۴۰۴ برمی‌گرداند؛ شناسهٔ مدل را از GET /models?type=moderation بگیرید.","requestBody":{"required":true,"content":{"application/json":{"example":{"input":"متن برای بررسی"}}}},"responses":{"200":{"description":"موفق"},"400":{"description":"درخواست نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست / سقف مصرف","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"مدل یا IP برای این کلید مجاز نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ (RPM / همزمانی / مدل‌های رایگان)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"خطای ارائه‌دهندهٔ مدل (هزینه‌ای کسر نمی‌شود)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"tags":["حساب و مصرف"],"summary":"موجودی و مشخصات کلید","responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"object":"account","balance":{"usd":"12.345678","usd_display":"$12.3457","toman_estimate":2580000},"status":"active","project":{"id":7,"name":"ربات تلگرام"},"key":{"name":"production","prefix":"sk-ntz-v1-ab12","rpm_limit":60,"spend_limit_usd":null,"spent_usd":"3.120000","expires_at":null},"limits":{"concurrency":8,"max_request_kb":4096}}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"tags":["حساب و مصرف"],"summary":"گزارش مصرف پروژه","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"example":"2026-08-01"},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group","in":"query","schema":{"type":"string","enum":["day","model"]}},{"name":"scope","in":"query","schema":{"type":"string","enum":["project","key"]},"description":"پیش‌فرض کل پروژه؛ `key` فقط همین کلید"}],"responses":{"200":{"description":"موفق","content":{"application/json":{"example":{"object":"usage","from":"2026-08-01","to":"2026-08-30","group":"day","total_usd":"4.210000","data":[{"key":"2026-08-30","requests":120,"errors":1,"input_tokens":45000,"output_tokens":12000,"usd":"0.310000"}]}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{id}":{"get":{"tags":["حساب و مصرف"],"summary":"وضعیت یک درخواست","description":"شناسه از هدر `X-Request-Id` یا فیلد `id` پاسخ.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"موفق"},"404":{"description":"مدل یافت نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}