راهنمای API هوش مصنوعی

راهنمای API هوش مصنوعیبه‌زودی

پیش‌نمایش: درخواستِ واقعی هنوز فعال نیست. می‌توانی کلید بسازی و با سازوکار آشنا شوی؛ تا وقتی اعتبار نداری پاسخِ «اعتبار کافی نیست» می‌گیری. شارژ و قیمت‌گذاری به‌زودی اعلام می‌شود.

با کلیدی که از پنل می‌گیری، از همین مدل‌ها در سایت و پروژه‌های شخصی‌ات استفاده کن. قالبِ درخواست و پاسخ مثلِ API های رایجِ چت است، پس کتابخانه‌های آماده معمولاً با عوض‌کردنِ آدرسِ پایه و کلید کار می‌کنند.

شروع مدل‌ها و قیمت هدرهای pyc تخفیفِ حجمی streaming Idempotency خطاها امنیت ورود · ثبت‌نام

۱) شروع

آدرس پایه: https://ai.pycourse.ir/v1

احراز هویت: هدر Authorization: Bearer pyc_sk_live_… — کلید را در پنل (بخشِ «کلیدها») می‌سازی و فقط یک بار کامل می‌بینی.

curl https://ai.pycourse.ir/v1/chat/completions \ -H "Authorization: Bearer $PYCOURSE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "pyc-lite", "messages": [{"role": "user", "content": "سلام! خودت را معرفی کن."}], "max_tokens": 200 }'

import os, requests r = requests.post( "https://ai.pycourse.ir/v1/chat/completions", headers={"Authorization": "Bearer " + os.environ["PYCOURSE_API_KEY"]}, json={ "model": "pyc-lite", "messages": [{"role": "user", "content": "سلام!"}], "max_tokens": 200, }, timeout=60, ) r.raise_for_status() data = r.json() print(data["choices"][0]["message"]["content"]) print(data["usage"]) # prompt_tokens, completion_tokens, total_tokens

// روی سرورِ خودت (Node 18+)؛ هرگز در کدِ مرورگر const res = await fetch("https://ai.pycourse.ir/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer " + process.env.PYCOURSE_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ model: "pyc-lite", messages: [{ role: "user", content: "سلام!" }], max_tokens: 200, }), }); if (!res.ok) throw new Error((await res.json()).error.message); const data = await res.json(); console.log(data.choices[0].message.content, data.usage);

آدرسِ پایه و نامِ مدل در مثال‌ها از همین صفحه پر شده؛ هر مدلِ دیگری از فهرستِ پایین را هم می‌توانی بگذاری. فهرستِ زنده‌ی مدل‌ها: GET https://ai.pycourse.ir/v1/models؛ توضیحِ هر سطح در صفحه‌ی مدل‌ها.

شروعِ سریع به‌زودی

۱) در بخشِ «کلیدها» یک کلید بساز و کامل کپی‌اش کن. ۲) فراخوانیِ بالا را با همان کلید اجرا کن. ۳) تا وقتی به کلید اعتبار اختصاص نداده‌ای (در صفحه‌ی «کلیدها» از کیف پولت به آن اعتبار بده) پاسخِ ۴۰۲ با insufficient_credit می‌گیری (نمونه‌اش پایین، در بخشِ خطاها). ۴) پس از اختصاصِ اعتبار، همین فراخوانی بدونِ هیچ تغییری پاسخِ واقعی می‌دهد. هر کلید فقط از اعتبارِ خودش خرج می‌کند.

پارامترها: model، messages (نقش‌های system/user/assistant)، max_tokens (اگر ندهی ۱۰۲۴؛ سقفِ هر مدل را ببین)، stream، temperature، top_p، stop. پارامتر ناشناخته ۴۰۰ می‌دهد. مدل‌های استدلالی ممکن است temperature، top_p یا stop را نپذیرند؛ در این صورت بی‌صدا کنار گذاشته می‌شوند و نامشان در هدرِ پاسخِ X-Pyc-Ignored-Params می‌آید (خطا نیست).

۲) مدل‌ها و قیمت‌ها به‌زودی

قیمت‌گذاری به‌زودی اعلام می‌شود. هر چه بیشتر مصرف کنی، هزینه‌ی هر توکن کمتر می‌شود.

فهرستِ زنده‌ی مدل‌ها را با GET https://ai.pycourse.ir/v1/models می‌گیری.

هدرهای pyc و توکنِ استدلال

هدرهای درخواست (اختیاری): X-Pyc-Quality: max برای درخواستِ بهترین کیفیت از pyc-auto؛ X-Pyc-Max-Tier: lite|plus|pro برای سقفِ سطح (هزینه‌ی مطمئن)؛ X-Pyc-Task: برچسب-کوتاه (حروفِ کوچک، عدد، «-» و «_»). مقدارِ نامعتبر ۴۰۰ می‌دهد. مدلِ صریح (مثلاً pyc-pro) هرگز عوض نمی‌شود.

هدرهای پاسخ: X-Pyc-Model-Used سطحِ واقعاً استفاده‌شده، X-Pyc-Ignored-Params پارامترهای کنارگذاشته‌شده، و X-Request-Id برای پیگیری.

توکنِ استدلال: مدل‌های استدلالی پیش از پاسخ «فکر می‌کنند»؛ این توکن‌ها جزئی از completion_tokens (خروجی) هستند و در usage.completion_tokens_details.reasoning_tokens دیده می‌شوند. سقفِ max_tokens فقط به متنِ پاسخ اعمال می‌شود و برای استدلال حاشیه‌ی جدا داریم؛ پس هزینه‌ی خروجی ممکن است از طولِ متن بیشتر باشد. اگر متنِ پاسخ کاملاً خالی بماند هزینه‌ای کسر نمی‌شود.

ظرفیت: اگر بودجه‌ی روزانه‌ی یک سطح یا سرویس تمام شود، پاسخِ ۵۰۳ با کدِ capacity_reached می‌گیری (رایگان). pyc-auto پیش از پر شدن، خودکار یک سطح پایین‌تر می‌آید.

۳) تخفیفِ حجمی و قاعده‌ی گرد‌کردن

هرچه بیشتر مصرف کنی، ارزان‌تر می‌شود. قیمت بر پایه‌ی مصرفِ تجمعیِ ماهانه‌ی خودت (جدا برای هر مدل و جدا برای ورودی و خروجی) پله‌پله پایین می‌آید؛ ماه از اولِ ماهِ میلادی به وقتِ تهران شروع می‌شود و صفر می‌شود.

جزئیاتِ پله‌ها و قیمت‌ها همراهِ اعلامِ قیمت‌گذاری منتشر می‌شود.

درخواستِ ناموفق هزینه ندارد: خطای ارائه‌دهنده، timeout و درخواست‌های ردشده (۴xx/۵xx) چیزی از اعتبارِ کلید کم نمی‌کنند. فقط اگر جریان (stream) را وسطِ راه قطع کنی، توکن‌هایی که تا آن لحظه تولید شده حساب می‌شود.

رزرو: پیش از هر درخواست، سقفِ هزینه‌اش (ورودی + max_tokens × قیمتِ خروجی) از موجودیِ قابل‌خرج «رزرو» می‌شود و پس از پاسخ، فقط هزینه‌ی واقعی کسر و باقی آزاد می‌شود. پس max_tokens را بزرگ‌تر از نیازت نگذار.

۴) Streaming (SSE)

با "stream": true پاسخ تکه‌تکه به‌صورت text/event-stream می‌آید: هر خط data: {…}، تکه‌ی آخر شاملِ usage و پایان با data: [DONE]. خطای پیش از شروعِ جریان با کدِ HTTP واقعی می‌آید؛ خطای وسطِ راه به‌شکلِ یک event با کلیدِ error و آن درخواست رایگان است.

curl -N https://ai.pycourse.ir/v1/chat/completions \ -H "Authorization: Bearer $PYCOURSE_API_KEY" -H "Content-Type: application/json" \ -d '{"model":"pyc-lite","stream":true,"messages":[{"role":"user","content":"سلام"}]}'

۵) Idempotency-Key

برای جلوگیری از کسرِ دوبار در تلاشِ دوباره (قطعِ شبکه، timeout سمتِ تو) هدر Idempotency-Key: یک-شناسه-یکتا بفرست (حروف/عدد/. _ : -، حداکثر ۱۲۰). اگر همان کلید برای همان API key دوباره بیاید، پاسخِ ۴۰۹ با request_id قبلی می‌گیری و هیچ هزینه‌ی دوباره‌ای کم نمی‌شود. (پاسخِ قبلی را نگه نمی‌داریم؛ متنِ پرامپت و پاسخ هرگز ذخیره نمی‌شود.)

۶) خطاها

همه‌ی خطاها یک قالبِ ثابت دارند: {"error": {"message": "…", "type": "…", "code": "…"}}. هدر X-Request-Id را برای پیگیری نگه دار.

نمونه‌ی پاسخِ ۴۰۲ (اعتبارِ کافی نیست):

{ "error": { "message": "اعتبارِ این کلید کافی نیست. از صفحه‌ی کلیدها اعتبارِ بیشتری از کیف پولت به آن اختصاص بده: https://pycourse.ir/ai/", "type": "insufficient_quota", "code": "insufficient_credit" } }

400 invalid_request

بدنه یا پارامتر نامعتبر (مثلاً max_tokens بیش از سقفِ مدل)

401 invalid_api_key

کلید نبود، قالبش درست نبود، نامعتبر یا ابطال‌شده بود

402 insufficient_credit

اعتبارِ کیف پول کافی نیست (کیف پولی نیست، موجودی صفر است، یا برای سقفِ هزینه‌ی این درخواست کفایت نمی‌کند)

403 key_cap_exceeded

سقفِ ماهانه‌ی همین کلید پر شده یا پر می‌شود

404 model_not_found

مدل وجود ندارد یا غیرفعال است

409 duplicate_request

همین Idempotency-Key قبلاً پردازش شده؛ دوباره کسر نمی‌شود

413 request_too_large

حجمِ بدنه از حدِ مجاز بیشتر است

429 rate_limit_exceeded

درخواست در دقیقه یا هم‌زمانیِ کلید از سقف بیشتر است — هدر Retry-After را ببین

502 provider_error

خطا از سمت ارائه‌دهنده — هزینه‌ای کسر نمی‌شود

503 service_disabled

سرویس خاموش/در حال خاموش‌شدن یا حسابداری در دسترس نیست — هزینه‌ای کسر نمی‌شود

503 capacity_reached

ظرفیتِ امروزِ این سطح/سرویس پر شده؛ کمی بعد (یا فردا) دوباره امتحان کن، یا سطحِ پایین‌تری را انتخاب کن — هزینه‌ای کسر نمی‌شود

504 provider_timeout

ارائه‌دهنده در زمانِ مقرر پاسخ نداد — هزینه‌ای کسر نمی‌شود

۷) امنیت

🔴 کلید را در کدِ سمتِ کاربر (جاوااسکریپتِ صفحه، اپِ موبایل، مخزنِ عمومی) نگذار. هر کس کلید را ببیند از اعتبارِ همان کلید خرج می‌کند. gateway عمداً CORS ندارد: مرورگر نمی‌تواند مستقیم صدایش بزند. درخواست را از سرورِ خودت بفرست.

کلید را در متغیرِ محیطی نگه دار، برای هر پروژه کلیدِ جدا بساز، سقفِ ماهانه بگذار، و اگر لو رفت همان لحظه از پنل «ابطال» کن (ابطال فوری است و برگشت ندارد). ما فقط یک اثرِ یک‌طرفه (hash) از کلید نگه می‌داریم، پس گم‌شدنش قابل‌بازیابی نیست.