تکمیل گفتگو (Chat Completions)

این نقطه پایانی برای تولید پاسخ‌های مکالمه‌ای از یک رشته پیام‌ها بهینه‌سازی شده است. این API برای مدل‌های مبتنی بر گفتگو طراحی شده است.

جزئیات نقطه پایانی (Endpoint)

POST

https://rahyana.ir/api/v1/chat/completions

هدرهای استاندارد

احراز هویت

(مانند Authorization: Bearer YOUR_API_KEY) مورد نیاز است. همچنین توصیه می‌شود هدرهای HTTP-Referer و X-Title را برای شناسایی بهتر برنامه خود ارسال کنید.

بدنه درخواست (Request Body)

بدنه درخواست باید یک آبجکت JSON معتبر با پارامترهای زیر باشد.

پارامتر	نوع	ضروری؟	توضیحات
model	string	بله	شناسه مدل مورد استفاده (مثال: `openai/gpt-4o`). برای لیست کامل مدل‌ها و شناسه‌ها به صفحه مدل‌ها مراجعه کنید.
messages	array	بله	آرایه‌ای از اشیاء پیام که تاریخچه گفتگو را تشکیل می‌دهند. هر پیام شامل `role` و `content` است.
stream	boolean	خیر	اگر `true` باشد، پاسخ به صورت جریانی (Server-Sent Events) ارسال می‌شود.
temperature	number	خیر	میزان خلاقیت پاسخ (معمولاً بین 0.0 تا 2.0). مقادیر بالاتر پاسخ‌های تصادفی‌تر و مقادیر پایین‌تر پاسخ‌های متمرکزتر تولید می‌کنند.
max_tokens	integer	خیر	حداکثر تعداد توکن‌هایی که مدل می‌تواند در پاسخ تولید کند.
top_p	number	خیر	روشی جایگزین برای کنترل خلاقیت با نمونه‌برداری هسته‌ای.
tools	array	خیر	لیستی از ابزارهایی که مدل می‌تواند فراخوانی کند.
tool_choice	string \| object	خیر	نحوه انتخاب ابزار توسط مدل را کنترل می‌کند.

ساختار پیام‌ها (Message Structure)

پارامتر	نوع	ضروری؟	توضیحات
role	string	بله	نقش پیام دهنده. می‌تواند `"system"`, `"user"`, `"assistant"`, یا `"tool"` باشد.
content	string \| array	بله	محتوای پیام. برای نقش `user` می‌تواند آرایه‌ای از متن و اشیاء تصویر باشد.
name	string	خیر	نام تابع (در صورتی که `role` برابر `tool` یا `assistant` با `tool_calls` باشد).
tool_call_id	string	خیر	شناسه فراخوانی ابزار که این پیام پاسخی به آن است.

نمونه‌های درخواست

curl -X POST "https://rahyana.ir/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Title: My cURL Test App" \
  -H "HTTP-Referer: https://example.com/curl-docs" \
  -d '{
    "model": "openai/chatgpt-4o-latest",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

ساختار پاسخ (Response Structure)

پاسخ غیرجریانی (Non-Streaming Response)

{
  "id": "cmpl-xxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1701387600,
  "model": "openai/gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "سلام! من یک مدل زبان بزرگ هستم که توسط گوگل آموزش دیده‌ام."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 15,
    "total_tokens": 36
  }
}

پاسخ جریانی (Streaming Response)

اگر stream: true باشد، پاسخ به صورت مجموعه‌ای از Server-Sent Events (SSE) با Content-Type: text/event-stream ارسال می‌شود. هر رویداد یک قطعه JSON از نوع chat.completion.chunk است. آخرین پیام data: [DONE] خواهد بود.

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"role":"assistant","content":"سلام!"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" من"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" یک"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" مدل"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" زبان"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" بزرگ"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" هستم"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" که"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" توسط"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" گوگل"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" آموزش"},"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" دیده‌ام."}
      ,"finish_reason":null}]}

data: {"id":"cmpl-xxxxxxxxxxxxxx","object":"chat.completion.chunk","created":1701387600,"model":"openai/gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

برای اطلاعات دقیق‌تر در مورد پردازش پاسخ‌های جریانی، به صفحه مستندات استریمینگ مراجعه کنید.

هدرهای پاسخ مربوط به Usage

پس از تکمیل موفقیت‌آمیز درخواست (چه در حالت استریم و چه غیر استریم)، API راهیانا هدرهای زیر را در پاسخ HTTP برمی‌گرداند که اطلاعات مربوط به مصرف توکن و اعتبار را ارائه می‌دهند:

هدر	نوع	توضیحات
X-Input-Tokens	integer	توکن‌های ورودی.
X-Output-Tokens	integer	توکن‌های خروجی.
X-Credits-Used	number	اعتبار مصرفی (تومان).
X-Credits-Remaining	number	اعتبار باقیمانده.

قابلیت‌های پیشرفته

این API از قابلیت‌های پیشرفته زیر پشتیبانی می‌کند:

فراخوانی ابزار (Tool Calling) - برای اجازه دادن به مدل برای فراخوانی توابع تعریف شده
ورودی تصویر و PDF - برای ارسال تصاویر و اسناد PDF به مدل‌های پشتیبانی‌کننده
حالت JSON - با تنظیم response_format: { "type": "json_object" } برای دریافت پاسخ‌های JSON معتبر