شروع سریع

به یک حساب مهوش و جایی برای اجرای کد سمت سرور نیاز دارید؛ مثلاً یک ترمینال با curl، یک پروژهٔ Node.js نسخهٔ ۱۸ یا بالاتر، یا Python نسخهٔ ۳٫۹ یا بالاتر. نمونه‌ها هرجا مناسب باشد از SDKهای رسمی OpenAI و در بقیهٔ موارد از HTTP ساده استفاده می‌کنند؛ بنابراین با هر زبانی می‌توانید همراه شوید.

وارد داشبورد مهوش شوید، پروژهٔ موردنظر را باز کنید (حساب شما از ابتدا یک پروژهٔ پیش‌فرض دارد) و یک API key بسازید. اسمی انتخاب کنید که نشان دهد کلید کجا استفاده می‌شود؛ مثلاً local-dev یا billing-service-prod.

کلید کامل فقط یک بار نمایش داده می‌شود. مهوش فقط hash کلید را نگه می‌دارد و دیگر نمی‌تواند آن را نشان دهد؛ اگر کلید را گم کردید، باید آن را rotate کنید یا کلید تازه بسازید. پیشوند کوتاه mk_... همیشه در داشبورد دیده می‌شود و برای شناسایی کلید امن است.

کلید را در یک متغیر محیطی یا سامانهٔ مدیریت secretها ذخیره کنید:

# .env on your server — never commit this file
MAHVASH_API_KEY=<shown-once-project-api-key>

هر API key پروژه به یک سازمان و یک پروژه تعلق دارد. هرچه با آن بسازید — response، فایل یا vector store — مال همان پروژه است و کلید به هیچ چیز در پروژه‌های دیگر دسترسی ندارد.

از مهوش بپرسید پروژهٔ شما همین حالا از چه مدل‌هایی می‌تواند استفاده کند:

curl https://api.mahvashai.ir/v1/models \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

هر مورد در این فهرست، یک مدل منطقی و قابلیت‌هایش را توصیف می‌کند. فیلدهایی که بیشتر به کارتان می‌آیند:

{
  "object": "list",
  "data": [
    {
      "id": "<model-id>",
      "object": "model",
      "owned_by": "<company>",
      "is_available": true,
      "supports_responses": true,
      "supports_chat_completions": true,
      "supports_streaming": true,
      "supports_json_mode": true,
      "reasoning": false,
      "context_window": 128000,
      "max_output_tokens": 16384
    }
  ]
}

• is_available: آیا مدل همین حالا قابل انتخاب است یا نه.
• supports_responses، supports_chat_completions و supports_streaming: مدل با کدام APIها و به چه شکلی کار می‌کند.
• supports_json_mode و reasoning: پشتیبانی از خروجی ساختاریافته و استدلال.
• context_window و max_output_tokens: محدودیت‌های حجم که هنگام ساختن prompt باید رعایت کنید.

Responses API بهترین نقطهٔ شروع برای یکپارچه‌سازی‌های متنی تازه است. ساده‌ترین request مفید فقط یک model و یک input دارد:

curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","input":"Say hello in one sentence."}'

با model: "auto" انتخاب مدل مناسب برای یک request گفت‌وگومحور را به مهوش می‌سپارید. اگر auto برای مسیر شما در دسترس نیست، یکی از شناسه‌هایی را بگذارید که GET /v1/models برگردانده است.

این request بدون stream است؛ یعنی اتصال HTTP تا آماده شدن کل پاسخ باز می‌ماند و در پایان یک شیء JSON برمی‌گردد.

فراخوانی موفق یک شیء response برمی‌گرداند:

{
  "id": "resp_<uuid>",
  "object": "response",
  "status": "completed",
  "model": "<model-id>",
  "output": [
    {
      "id": "msg_<id>",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "Hello! It is nice to meet you.", "annotations": [] }
      ]
    }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 9, "total_tokens": 21 }
}

• id شناسهٔ ثابت این response است. اگر ممکن است بعداً پاسخ را دوباره بگیرید، گفت‌وگو را ادامه دهید یا مشکلی را بررسی کنید، آن را ذخیره کنید.
• status برای پاسخ کامل completed است. مقدارهای دیگری مثل incomplete یا failed را در production باید مدیریت کنید.
• output یک فهرست است، نه یک رشتهٔ ساده. پاسخ معمولی یک آیتم از نوع message است که content آن شامل بخش‌های output_text است. فراخوانی ابزار، خلاصهٔ استدلال یا فایل ساخته‌شده به‌صورت آیتم‌های جداگانه می‌آیند.
• usage تعداد tokenهای ورودی، خروجی و مجموع آن‌ها را نشان می‌دهد.

SDKها ویژگی کمکی output_text را دارند که متن را برایتان سرهم می‌کند. اگر از SDK استفاده نمی‌کنید، متن را خودتان جمع کنید:

// Without the SDK: collect every output_text part of every message item.
const text = result.output
  .filter((item) => item.type === "message")
  .flatMap((item) => item.content)
  .filter((part) => part.type === "output_text")
  .map((part) => part.text)
  .join("");

console.log(result.id, result.status, text);
console.log("request id:", response.headers.get("X-Request-ID"));

هر پاسخ یک header به نام X-Request-ID هم دارد. آن را در لاگ ثبت کنید؛ سریع‌ترین راه برای اینکه تیم پشتیبانی بفهمد دقیقاً چه بر سر یک request آمده، همین شناسه است.

حالا یک یکپارچه‌سازی کارا دارید. آن را کم‌کم کامل کنید:

• متن را همزمان با تولیدش نمایش دهید: Stream و رویدادها.
• برای ادامهٔ گفت‌وگو، id پاسخ قبلی را در previous_response_id بفرستید.
• از روی اسناد خودتان پاسخ بدهید: ورودی فایل و بازیابی اطلاعات.
• تکرار request را با Idempotency-Key امن کنید و همهٔ انواع خطا را مدیریت کنید: Headerها و ساختار Response.
• برای انتشار آماده شوید: چک‌لیست اتصال در محیط اصلی.

همهٔ فیلدهای مجاز request‌ای که فرستادید، در مرجع Responses آمده است.