Chat Completions

اندپوینت اصلی برای گفت‌وگو با مدل‌های زبانی. سازگار با OpenAI Chat Completions.

اندپوینت

POSThttps://api.hooshgar.ir/v1/chat/completions

پارامترها

پارامتر	نوع	اجباری	توضیح
model	string	بله	شناسۀ مدل، مثلاً openai/gpt-4o یا claude-sonnet-4.
messages	array	بله	پیام‌ها با نقش‌های system / user / assistant / tool.
temperature	number	—	میزان خلاقیت (۰ تا ۲). پیش‌فرض ۱.
top_p	number	—	نمونه‌گیری هستۀ احتمال.
max_tokens	integer	—	سقف توکن خروجی.
n	integer	—	تعداد پاسخ.
stream	boolean	—	دریافت پاسخ به‌صورت SSE.
stop	string \| string[]	—	توکن‌های توقف.
presence_penalty	number	—	جریمۀ حضور موضوع (‎-2 تا 2).
frequency_penalty	number	—	جریمۀ تکرار (‎-2 تا 2).
response_format	object	—	‏{ type: "json_object" \| "json_schema" } برای خروجی ساخت‌یافته.
tools	array	—	فهرست ابزارها برای Function Calling.
tool_choice	string \| object	—	auto / none / ابزار مشخص.
user	string	—	شناسۀ کاربر نهایی برای لاگ و پایش سوءاستفاده.
seed	integer	—	برای تلاش در بازتولیدپذیری خروجی.

نمونۀ درخواست

curl -X POST https://api.hooshgar.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HOOSHGAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "system", "content": "تو یک دستیار فارسی‌زبان و مؤدبی."},
      {"role": "user",   "content": "یک متن تبلیغاتی کوتاه برای یک اپ تاکسی بنویس."}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

نمونۀ پاسخ

{
  "id": "chatcmpl_01H...",
  "object": "chat.completion",
  "created": 1717000000,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "با هوش مصنوعی هوشگر، سفرت را هوشمندانه شروع کن…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 90,
    "total_tokens": 132
  }
}

ورودی چندرسانه‌ای (Vision)

مدل‌هایی که از تصویر پشتیبانی می‌کنند، می‌توانند در محتوای پیام آرایه‌ای از بخش‌های متن و تصویر دریافت کنند:

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "این تصویر چیست؟" },
        { "type": "image_url", "image_url": { "url": "https://example.com/pic.jpg" } }
      ]
    }
  ]
}

خروجی ساخت‌یافته (JSON)

{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "user", "content": "نام و ایمیل را از این متن استخراج کن: علی احمدی a@x.ir"}
  ],
  "response_format": { "type": "json_object" }
}

قابلیت‌ها در مدل‌های مختلف متفاوت است و نام مدل در نمونه‌ها فقط برای مثال است. پیش از استفاده، شناسهٔ دقیق مدل و قابلیت‌های آن را در کاتالوگ مدل‌های هوشگر بررسی کنید.