{"openapi":"3.1.0","info":{"title":"وب‌سرویس هوش مصنوعی گیسو","version":"1.0.0","summary":"API سازگار با OpenAI برای صدها مدل هوش مصنوعی، بدون کارت خارجی و به‌اندازهٔ مصرف.","description":"با یک کلید و یک نشانی به مدل‌های OpenAI، Google Gemini، Anthropic Claude، DeepSeek، xAI Grok، Qwen، Mistral، Llama و ده‌ها سازندهٔ دیگر وصل شوید. فهرست زندهٔ مدل‌ها و قیمت‌ها در `GET /models` است.\n\n**سازگار با OpenAI:** در SDK رسمی OpenAI فقط `base_url` را `https://gisoo.pro/api/v1` بگذارید و کلید گیسو را جای کلید OpenAI بدهید. همین کد برای Claude و Gemini هم کار می‌کند.\n\n**کلید دسترسی:** هدر `Authorization: Bearer sk-gisoo-v1-…` (یا `X-API-Key`). کلید را در اپ گیسو، بخش «API» بسازید: https://gisoo.pro/app/api — کلیدهای `sk-ntz-v1-…` که در نِت اَرز ساخته‌اید هم همین‌جا کار می‌کنند.\n\n**هزینه:** هر درخواست بر پایهٔ مصرف واقعی (توکن، تصویر، دقیقهٔ صوت، ثانیهٔ ویدیو یا نویسه) از اعتبار دلاری حساب کم می‌شود. درخواستی که پیش از تولید پاسخ با خطای سازندهٔ مدل تمام شود هزینه‌ای ندارد.\n\n**محدودیت‌های پیش‌فرض:** ۶۰ درخواست در دقیقه برای هر کلید، ۸ درخواست همزمان برای هر حساب و بدنهٔ حداکثر ۲۰ مگابایت (فایل صوتی تا ۲۵ مگابایت). مقدار واقعی حساب شما را `GET /me` برمی‌گرداند. پیش از احراز هویت، سقف کل مصرف ۲ دلار است.\n\nراهنمای کامل: https://gisoo.pro/docs","contact":{"name":"پشتیبانی گیسو","url":"https://gisoo.pro/docs/faq"},"termsOfService":"https://gisoo.pro/terms"},"externalDocs":{"description":"مستندات فارسی گیسو","url":"https://gisoo.pro/docs"},"servers":[{"url":"https://gisoo.pro/api/v1","description":"گیسو (base_url)"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"مدل‌ها","description":"فهرست مدل‌ها و قیمت‌ها؛ بدون کلید"},{"name":"متن و گفت‌وگو","description":"Chat Completions، Responses و Completions"},{"name":"امبدینگ","description":"تبدیل متن به بردار برای جست‌وجوی معنایی و RAG"},{"name":"تصویر","description":"ساخت تصویر از توصیف متنی"},{"name":"صدا","description":"گفتار به متن، ترجمهٔ صوت و متن به گفتار"},{"name":"ویدیو","description":"ساخت ویدیو؛ کار ناهمگام"},{"name":"موسیقی","description":"ساخت قطعهٔ موسیقی از توصیف"},{"name":"پایش محتوا","description":"Moderations"},{"name":"حساب و مصرف","description":"موجودی، محدودیت‌ها و گزارش مصرف"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"کلید گیسو: sk-gisoo-v1-… (کلید sk-ntz-v1-… هم پذیرفته می‌شود)"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"همان کلید، برای ابزارهایی که هدر Authorization نمی‌فرستند"}},"headers":{"X-Request-Id":{"description":"شناسهٔ درخواست در گیسو؛ برای پیگیری با GET /requests/{id} یا پشتیبانی","schema":{"type":"string","example":"req_4b1f0c9a7e2d8f3a6c5b0e1d"}}},"schemas":{"Error":{"type":"object","description":"قالب خطای OpenAI. `code` پایدار است و برای تصمیم در کد، `message` برای خواندن آدم.","required":["error"],"properties":{"error":{"type":"object","properties":{"message":{"type":"string","example":"اعتبار کافی نیست. موجودی $0.0120، مورد نیاز برای این درخواست حداقل $0.0400. حساب خود را شارژ کنید."},"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","insufficient_quota","rate_limit_error","upstream_error","service_unavailable"]},"code":{"type":["string","null"],"example":"insufficient_credit"},"param":{"type":["string","null"],"example":null}}}}},"Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","example":24},"completion_tokens":{"type":"integer","example":96},"total_tokens":{"type":"integer","example":120},"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"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"type":"object","title":"text","required":["type","text"],"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}}},{"type":"object","title":"image_url","required":["type","image_url"],"properties":{"type":{"type":"string","const":"image_url"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"https://… یا data:image/png;base64,…"},"detail":{"type":"string","enum":["auto","low","high"]}}}}},{"type":"object","title":"input_audio","required":["type","input_audio"],"properties":{"type":{"type":"string","const":"input_audio"},"input_audio":{"type":"object","properties":{"data":{"type":"string","description":"base64"},"format":{"type":"string","enum":["mp3","wav"]}}}}}]}},{"type":"null"}]},"name":{"type":"string"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"}},"tool_call_id":{"type":"string","description":"برای نقش tool: شناسهٔ فراخوانی‌ای که به آن پاسخ می‌دهید"}}},"Tool":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"get_weather"},"description":{"type":"string"},"parameters":{"type":"object","description":"JSON Schema ورودی تابع"},"strict":{"type":"boolean"}}}}},"ToolCall":{"type":"object","properties":{"id":{"type":"string","example":"call_8KqX2m"},"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string"},"arguments":{"type":"string","description":"رشتهٔ JSON؛ پیش از استفاده parse و اعتبارسنجی کنید"}}}}},"Model":{"type":"object","properties":{"id":{"type":"string","example":"gpt-4o-mini","description":"همان مقداری که در فیلد model می‌فرستید"},"object":{"type":"string","const":"model"},"owned_by":{"type":"string","example":"openai","description":"مسیر تأمین (openai، google، deepseek یا openrouter)"},"name":{"type":"string"},"type":{"type":"string","example":"chat"},"description":{"type":["string","null"]},"context_length":{"type":["integer","null"],"example":128000},"max_output_tokens":{"type":["integer","null"]},"capabilities":{"type":"object","example":{"streaming":true,"tools":true,"json":true,"vision":true}},"is_free":{"type":"boolean"},"pricing":{"type":"object","description":"دلار؛ به‌ازای یک میلیون توکن مگر آن‌که نام کلید چیز دیگری بگوید (per_image، per_minute، per_second، per_million_characters، per_request)","example":{"input_per_million":"0.210000","output_per_million":"0.840000","cached_input_per_million":"0.105000"}},"pricing_unit":{"type":"string"}}},"ChatRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","example":"gpt-4o-mini"},"messages":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Message"}},"stream":{"type":"boolean","default":false},"max_tokens":{"type":"integer","description":"سقف توکن خروجی. تعیین آن مبلغی را که پیش از پاسخ رزرو می‌شود کم می‌کند."},"max_completion_tokens":{"type":"integer","description":"نام تازهٔ max_tokens در مدل‌های استدلالی OpenAI؛ هر دو پذیرفته می‌شوند"},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number"},"n":{"type":"integer","minimum":1,"maximum":4,"default":1},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"presence_penalty":{"type":"number"},"frequency_penalty":{"type":"number"},"seed":{"type":"integer"},"response_format":{"type":"object","description":"{\"type\":\"json_object\"} یا {\"type\":\"json_schema\",\"json_schema\":{…}}"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"tool_choice":{"oneOf":[{"type":"string","enum":["none","auto","required"]},{"type":"object"}]},"parallel_tool_calls":{"type":"boolean"},"reasoning_effort":{"type":"string","enum":["minimal","low","medium","high"],"description":"برای مدل‌های استدلالی؛ در Claude به بودجهٔ فکر کردن تبدیل می‌شود"},"logprobs":{"type":"boolean"},"user":{"type":"string","description":"پذیرفته می‌شود ولی گیسو شناسهٔ خودش را به سازنده می‌فرستد"}}},"ChatResponse":{"type":"object","properties":{"id":{"type":"string","example":"req_4b1f0c9a7e2d8f3a6c5b0e1d"},"object":{"type":"string","const":"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"}}},"ResponsesRequest":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","example":"gpt-4.1-mini"},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object"}}]},"instructions":{"type":"string"},"tools":{"type":"array","items":{"type":"object"},"description":"مثل [{\"type\":\"web_search\"}] یا تابع‌های خودتان"},"max_output_tokens":{"type":"integer"},"stream":{"type":"boolean"},"previous_response_id":{"type":"string"}}},"EmbeddingRequest":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","example":"text-embedding-3-small"},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"dimensions":{"type":"integer","description":"کوتاه کردن بردار (مدل‌های text-embedding-3 و Gemini)"},"encoding_format":{"type":"string","enum":["float","base64"]}}},"ImageRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","example":"gpt-image-1-mini"},"prompt":{"type":"string"},"size":{"type":"string","example":"1024x1024"},"quality":{"type":"string","enum":["low","medium","high","auto"]},"n":{"type":"integer","minimum":1,"maximum":10,"default":1},"background":{"type":"string","enum":["transparent","opaque","auto"]},"output_format":{"type":"string","enum":["png","jpeg","webp"]}}},"TranscriptionRequest":{"type":"object","required":["file","model"],"properties":{"file":{"type":"string","format":"binary","description":"حداکثر ۲۵ مگابایت"},"model":{"type":"string","example":"gpt-4o-mini-transcribe"},"language":{"type":"string","example":"fa"},"prompt":{"type":"string","description":"واژه‌های خاص (نام‌ها، اصطلاحات) برای دقت بیشتر"},"response_format":{"type":"string","enum":["json","text","srt","vtt","verbose_json"]},"temperature":{"type":"number"},"timestamp_granularities":{"type":"array","items":{"type":"string","enum":["word","segment"]}}}},"SpeechRequest":{"type":"object","required":["model","input","voice"],"properties":{"model":{"type":"string","example":"gpt-4o-mini-tts"},"input":{"type":"string","maxLength":4096},"voice":{"type":"string","example":"alloy","description":"alloy، echo، fable، onyx، nova، shimmer و صداهای تازه‌تر هر مدل"},"instructions":{"type":"string","description":"لحن و حالت گفتار (فقط مدل‌های gpt-4o-mini-tts)"},"response_format":{"type":"string","enum":["mp3","opus","aac","flac","wav","pcm"]},"speed":{"type":"number","minimum":0.25,"maximum":4}}},"MusicRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","example":"openrouter/google/lyria-3-clip-preview"},"prompt":{"type":"string","maxLength":4000,"description":"سبک، ساز، حال‌وهوا، سرعت؛ برای آهنگ با کلام، متن شعر را هم بنویسید"},"temperature":{"type":"number"},"seed":{"type":"integer"}}},"VideoRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","example":"sora-2"},"prompt":{"type":"string","maxLength":4000},"seconds":{"type":"string","enum":["4","8","12"],"default":"4"},"size":{"type":"string","enum":["1280x720","720x1280","1792x1024","1024x1792","auto"],"default":"auto","description":"اندازه‌های مجاز هر مدل در capabilities.sizes آن آمده است"}}},"VideoJob":{"type":"object","properties":{"id":{"type":"string","example":"vid_7c2e9b4f1a0d3e8c6b5a2f1e"},"object":{"type":"string","const":"video"},"created_at":{"type":"integer"},"completed_at":{"type":["integer","null"]},"expires_at":{"type":["integer","null"]},"model":{"type":"string","example":"sora-2"},"status":{"type":"string","enum":["queued","in_progress","completed","failed"]},"progress":{"type":"integer","minimum":0,"maximum":100},"seconds":{"type":"string","example":"8"},"size":{"type":"string","example":"1280x720"},"usd":{"type":"string","description":"هزینهٔ این ویدیو به دلار"},"refunded":{"type":"boolean","description":"true یعنی ویدیو ساخته نشد و هزینه برگشت"},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Account":{"type":"object","example":{"object":"account","balance":{"usd":"12.408114","usd_display":"$12.4081"},"status":"active","project":{"id":42,"name":"chatbot"},"key":{"name":"production","prefix":"sk-gisoo-v1-Xy7Q","rpm_limit":60,"spend_limit_usd":"20.00","spent_usd":"3.591886","expires_at":null},"limits":{"concurrency":8,"max_request_kb":20480}},"properties":{"object":{"type":"string","const":"account"},"balance":{"type":"object","properties":{"usd":{"type":"string"},"usd_display":{"type":"string"}}},"status":{"type":"string","enum":["active","suspended"]},"project":{"type":"object"},"key":{"type":"object"},"limits":{"type":"object"}}},"UsageReport":{"type":"object","example":{"object":"usage","from":"2026-09-01","to":"2026-09-30","group":"day","total_usd":"1.284000","data":[{"key":"2026-09-29","requests":88,"errors":1,"input_tokens":41200,"output_tokens":9800,"usd":"0.061000"}]},"properties":{"object":{"type":"string","const":"usage"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"group":{"type":"string","enum":["day","model"]},"total_usd":{"type":"string"},"data":{"type":"array","items":{"type":"object"}}}},"RequestStatus":{"type":"object","example":{"id":"req_4b1f0c9a7e2d8f3a6c5b0e1d","object":"request","created":1790000000,"model":"gpt-4o-mini","endpoint":"chat","status":"success","streamed":true,"usage":{"input_tokens":24,"output_tokens":96,"cached_tokens":0,"total_tokens":120},"usd":"0.000086","latency_ms":1840,"error":null},"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","success","error","cancelled"]},"usd":{"type":"string"}}}}},"paths":{"/models":{"get":{"tags":["مدل‌ها"],"operationId":"listModels","summary":"فهرست مدل‌ها و قیمت‌ها","security":[],"description":"همهٔ مدل‌هایی که امروز فروخته می‌شوند، با قیمت دلاری. با `type` یک خانواده را جدا کنید. قیمت‌ها به‌ازای یک میلیون توکن‌اند مگر آن‌که نام کلید چیز دیگری بگوید.","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["chat","embedding","image","audio_stt","audio_tts","video","music","moderation"]}}],"responses":{"200":{"description":"فهرست مدل‌ها","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}}}}},"/models/{id}":{"get":{"tags":["مدل‌ها"],"operationId":"retrieveModel","summary":"مشخصات و قیمت یک مدل","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"شناسهٔ مدل؛ ممکن است / داشته باشد (مثل openrouter/anthropic/…)","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":["متن و گفت‌وگو"],"operationId":"createChatCompletion","summary":"گفت‌وگو (Chat Completions)","description":"همان قالب OpenAI. برای همهٔ مدل‌های متنی — Claude، Gemini، DeepSeek و مدل‌های OpenRouter — هم همین endpoint و همین بدنه را بفرستید.\n\nبا `stream: true` پاسخ به شکل Server-Sent Events می‌آید: رویدادهای `data: {…}` و در پایان `data: [DONE]`؛ رویداد یکی‌مانده به آخر `usage` را دارد.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"examples":{"simple":{"summary":"پرسش ساده","value":{"model":"gpt-4o-mini","messages":[{"role":"system","content":"You are a concise assistant. Answer in Persian."},{"role":"user","content":"سه ایده برای نام یک کافه‌کتاب بده."}],"max_tokens":300}},"json":{"summary":"خروجی JSON با طرح‌واره","value":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Extract the city and date: «جلسه پنجشنبه در شیراز است»"}],"response_format":{"type":"json_schema","json_schema":{"name":"event","strict":true,"schema":{"type":"object","additionalProperties":false,"required":["city","day"],"properties":{"city":{"type":"string"},"day":{"type":"string"}}}}}}},"tools":{"summary":"فراخوانی ابزار","value":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"هوای تبریز الان چطور است؟"}],"tools":[{"type":"function","function":{"name":"get_weather","description":"Current weather for a city","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}]}},"claude":{"summary":"همان بدنه با Claude","value":{"model":"openrouter/anthropic/claude-sonnet-4.5","messages":[{"role":"user","content":"Summarise the SOLID principles in five short lines."}],"max_tokens":400}}}}}},"responses":{"200":{"description":"پاسخ کامل (یا جریان SSE وقتی stream=true)","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}},"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"id\":\"req_…\",\"object\":\"chat.completion.chunk\",\"model\":\"gpt-4o-mini\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"سلام\"},\"finish_reason\":null}]}\n\ndata: {\"id\":\"req_…\",\"object\":\"chat.completion.chunk\",\"choices\":[],\"usage\":{\"prompt_tokens\":12,\"completion_tokens\":2,\"total_tokens\":14}}\n\ndata: [DONE]\n\n"}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/responses":{"post":{"tags":["متن و گفت‌وگو"],"operationId":"createResponse","summary":"Responses API","description":"Responses API از OpenAI، بدون تغییر. مطمئن‌ترین انتخاب برای این مسیر مدل‌های OpenAI است. ابزارهای داخلی مثل `web_search` کار می‌کنند و هزینهٔ هر فراخوانی ابزار جدا به صورتحساب اضافه می‌شود. `stream: true` رویدادهای Responses را برمی‌گرداند.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsesRequest"},"example":{"model":"gpt-4.1-mini","input":"What changed in the latest PHP release? Answer in two lines.","tools":[{"type":"web_search"}]}}}},"responses":{"200":{"description":"شیء response (قالب OpenAI)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/completions":{"post":{"tags":["متن و گفت‌وگو"],"operationId":"createCompletion","summary":"Completions (قالب قدیمی)","description":"برای ابزارهای قدیمی. `prompt` به یک پیام کاربر تبدیل می‌شود و پاسخ در قالب `text_completion` برمی‌گردد. کد تازه را با /chat/completions بنویسید.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"gpt-4o-mini","prompt":"Write a haiku about Tehran rain.","max_tokens":60}}}},"responses":{"200":{"description":"text_completion"},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/embeddings":{"post":{"tags":["امبدینگ"],"operationId":"createEmbedding","summary":"امبدینگ متن","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"},"example":{"model":"text-embedding-3-small","input":["سفارش من کی می‌رسد؟","زمان تحویل سفارش"]}}}},"responses":{"200":{"description":"بردارها","content":{"application/json":{"example":{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.0182,-0.0041,0.0333]}],"model":"text-embedding-3-small","usage":{"prompt_tokens":14,"total_tokens":14}}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/generations":{"post":{"tags":["تصویر"],"operationId":"createImage","summary":"ساخت تصویر","description":"خروجی همیشه base64 است (`data[].b64_json`). اندازه و کیفیت قیمت را جابه‌جا می‌کنند؛ اندازه‌های مجاز هر مدل در `capabilities.sizes` آن مدل در GET /models آمده است.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"},"example":{"model":"gpt-image-1-mini","prompt":"A minimalist poster of Mount Damavand at sunrise, warm gold tones, no text","size":"1024x1024","quality":"medium","n":1}}}},"responses":{"200":{"description":"تصویر","content":{"application/json":{"example":{"created":1790000000,"data":[{"b64_json":"iVBORw0KGgoAAAANSUhEUgAA…"}]}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/transcriptions":{"post":{"tags":["صدا"],"operationId":"createTranscription","summary":"گفتار به متن","description":"فایل را به شکل multipart/form-data در فیلد `file` بفرستید (حداکثر ۲۵ مگابایت: mp3، mp4، m4a، wav، webm، ogg). `language=fa` دقت فارسی را بالا می‌برد. زیرنویس با `response_format=srt` یا `vtt`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/TranscriptionRequest"}}}},"responses":{"200":{"description":"متن","content":{"application/json":{"example":{"text":"سلام، این یک پیام آزمایشی است."}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست یا سقف هزینهٔ کلید/پروژه/روز پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/translations":{"post":{"tags":["صدا"],"operationId":"createTranslation","summary":"ترجمهٔ صوت به متن انگلیسی","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","model"],"properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string","example":"whisper-1"},"response_format":{"type":"string","enum":["json","text","srt","vtt","verbose_json"]}}}}}},"responses":{"200":{"description":"متن انگلیسی","content":{"application/json":{"example":{"text":"Hello, this is a test message."}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"اعتبار کافی نیست یا سقف هزینهٔ کلید/پروژه/روز پر شده است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/speech":{"post":{"tags":["صدا"],"operationId":"createSpeech","summary":"متن به گفتار","description":"فایل صوتی (پیش‌فرض mp3) را مستقیم برمی‌گرداند. قیمت به‌ازای تعداد نویسهٔ متن است؛ حداکثر ۴۰۹۶ نویسه در هر درخواست.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechRequest"},"example":{"model":"gpt-4o-mini-tts","input":"Welcome to our podcast. Today we talk about coffee.","voice":"alloy","response_format":"mp3"}}}},"responses":{"200":{"description":"فایل صوتی","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audio/music":{"post":{"tags":["موسیقی"],"operationId":"createMusic","summary":"ساخت موسیقی","description":"یک قطعهٔ کامل را یک‌جا برمی‌گرداند (MP3 در قالب base64). قیمت به‌ازای هر قطعه است، نه توکن. مدل‌های موسیقی را به /chat/completions نفرستید.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MusicRequest"},"example":{"model":"openrouter/google/lyria-3-clip-preview","prompt":"Calm lo-fi piano with soft rain in the background, no vocals"}}}},"responses":{"200":{"description":"قطعه","content":{"application/json":{"example":{"id":"req_…","object":"music.generation","model":"openrouter/google/lyria-3-clip-preview","text":"<instrumental>","data":[{"b64_json":"SUQzBAAAAAAA…","format":"mp3","bytes":744608}]}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos":{"post":{"tags":["ویدیو"],"operationId":"createVideo","summary":"شروع ساخت ویدیو","description":"ساخت ویدیو یکی دو دقیقه طول می‌کشد، پس این مسیر فایل برنمی‌گرداند؛ یک «کار» با شناسهٔ `vid_…` برمی‌گرداند. وضعیت را با GET /videos/{id} بپرسید و وقتی `completed` شد فایل را از GET /videos/{id}/content بگیرید. هزینه همان لحظهٔ پذیرش کم می‌شود و اگر ویدیو ساخته نشود، خودکار برمی‌گردد.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"},"example":{"model":"sora-2","prompt":"Slow aerial shot over a misty tea plantation in Lahijan at dawn","seconds":"8","size":"1280x720"}}}},"responses":{"200":{"description":"کار پذیرفته شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoJob"}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["ویدیو"],"operationId":"listVideos","summary":"ویدیوهای این پروژه","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"فهرست، تازه‌ترین اول","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoJob"}}}}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}":{"get":{"tags":["ویدیو"],"operationId":"retrieveVideo","summary":"وضعیت یک ویدیو","description":"`status`: queued، in_progress، completed یا failed. هر ۱۰ تا ۲۰ ثانیه یک بار بپرسید.","parameters":[{"name":"id","in":"path","required":true,"description":"شناسهٔ کار","schema":{"type":"string"},"example":"vid_7c2e9b4f1a0d3e8c6b5a2f1e"}],"responses":{"200":{"description":"کار","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoJob"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یا منبع پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ویدیو"],"operationId":"deleteVideo","summary":"لغو یا حذف ویدیو","description":"ویدیویی که هنوز تحویل نشده لغو می‌شود و هزینه‌اش برمی‌گردد.","parameters":[{"name":"id","in":"path","required":true,"description":"شناسهٔ کار","schema":{"type":"string"},"example":"vid_7c2e9b4f1a0d3e8c6b5a2f1e"}],"responses":{"200":{"description":"حذف شد"},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یا منبع پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}/content":{"get":{"tags":["ویدیو"],"operationId":"downloadVideo","summary":"دریافت فایل ویدیو","description":"فایل MP4. `variant=thumbnail` تصویر کوچک و `variant=spritesheet` نوار فریم‌ها را می‌دهد؛ `download=1` فایل را برای ذخیره می‌فرستد. فایل تا حدود ۴۸ ساعت پس از ساخت در دسترس است.","parameters":[{"name":"id","in":"path","required":true,"description":"شناسهٔ کار","schema":{"type":"string"},"example":"vid_7c2e9b4f1a0d3e8c6b5a2f1e"},{"name":"variant","in":"query","schema":{"type":"string","enum":["video","thumbnail","spritesheet"],"default":"video"}},{"name":"download","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"فایل","content":{"video/mp4":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یا منبع پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/moderations":{"post":{"tags":["پایش محتوا"],"operationId":"createModeration","summary":"پایش محتوا","description":"قالب OpenAI Moderations. پیش از استفاده با `GET /models?type=moderation` ببینید مدلی فعال هست یا نه؛ اگر نباشد، پاسخ ۴۰۴ است.","requestBody":{"required":true,"content":{"application/json":{"example":{"input":"Text to check"}}}},"responses":{"200":{"description":"نتیجه (قالب OpenAI)"},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"tags":["حساب و مصرف"],"operationId":"getAccount","summary":"موجودی و محدودیت‌های همین کلید","responses":{"200":{"description":"حساب","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"این کلید اجازهٔ این مدل یا این IP را ندارد، یا احراز هویت لازم است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"tags":["حساب و مصرف"],"operationId":"getUsage","summary":"گزارش مصرف پروژه","description":"پیش‌فرض ۳۰ روز اخیر، روزبه‌روز. `group=model` مصرف را به تفکیک مدل می‌دهد و `scope=key` فقط همین کلید را.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"example":"2026-09-30"},{"name":"group","in":"query","schema":{"type":"string","enum":["day","model"],"default":"day"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["project","key"],"default":"project"}}],"responses":{"200":{"description":"گزارش","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{id}":{"get":{"tags":["حساب و مصرف"],"operationId":"getRequest","summary":"وضعیت و هزینهٔ یک درخواست","description":"شناسه همان `id` پاسخ یا هدر `X-Request-Id` است. فقط درخواست‌های همین پروژه دیده می‌شوند.","parameters":[{"name":"id","in":"path","required":true,"description":"شناسهٔ درخواست","schema":{"type":"string"},"example":"req_4b1f0c9a7e2d8f3a6c5b0e1d"}],"responses":{"200":{"description":"درخواست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestStatus"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"مدل یا منبع پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages":{"post":{"tags":["متن و گفت‌وگو"],"operationId":"createMessage","summary":"Messages (سازگار با Anthropic)","description":"همان قالب Messages API از Anthropic، برای SDK رسمی Anthropic و Claude Code. در SDK مقدار `base_url` را `https://gisoo.pro/api` بگذارید (SDK خودش `/v1/messages` را اضافه می‌کند). هر مدل متنی گیسو را می‌توانید بخواهید؛ نام‌هایی مثل `claude-sonnet-4-5` به مدل Claude همان نسخه در کاتالوگ گیسو می‌رسند. هدر `x-api-key` یا `Authorization: Bearer`. با `stream: true` رویدادهای message_start … message_stop می‌آیند.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"claude-sonnet-4-5","max_tokens":512,"system":"Answer in Persian.","messages":[{"role":"user","content":"Explain the difference between a process and a thread in three lines."}]}}}},"responses":{"200":{"description":"پیام (قالب Anthropic) یا جریان رویدادها","content":{"application/json":{"example":{"id":"msg_req_…","type":"message","role":"assistant","model":"claude-sonnet-4-5","content":[{"type":"text","text":"…"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":31,"output_tokens":120}}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","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"}}}},"413":{"description":"حجم درخواست از سقف مجاز بیشتر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"سقف درخواست در دقیقه یا درخواست همزمان پر شده است؛ هدر Retry-After را ببینید","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"سازندهٔ مدل پاسخ نداد؛ از اعتبار شما چیزی کم نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس یا مدل موقتاً در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/count_tokens":{"post":{"tags":["متن و گفت‌وگو"],"operationId":"countMessageTokens","summary":"برآورد توکن ورودی (سازگار با Anthropic)","description":"برآورد تعداد توکن ورودی یک درخواست Messages، بدون فرستادن آن به مدل و بدون هزینه. عدد برآورد است، نه شمارش دقیق سازنده.","requestBody":{"required":true,"content":{"application/json":{"example":{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"Hello"}]}}}},"responses":{"200":{"description":"برآورد","content":{"application/json":{"example":{"input_tokens":9}}}},"400":{"description":"بدنه یا پارامتر نادرست (کد خطا در error.code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"کلید دسترسی نرسیده، نادرست، باطل‌شده یا منقضی است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}