# مرجع API

API اهوس‌ای‌آی مدل نیمبوس ۲ ایپکس را در قالب Chat Completions شرکت OpenAI ارائه می‌کند. کتابخانه‌های موجود OpenAI پس از تغییر نشانی پایه و کلید، بدون تغییر دیگری با آن کار می‌کنند.

## نشانی پایه {#base-url}

```text
https://ahoos-ai.site/services/api/v1
```

| روش | مسیر | کاربرد |
|---|---|---|
| `GET` | `/models` | فهرست مدل‌های در دسترس |
| `POST` | `/chat/completions` | تولید پاسخ برای یک گفتگو |

## احراز هویت {#authentication}

هر درخواست به `/chat/completions` باید یک کلید API را در سرآیند `Authorization` همراه داشته باشد:

```text
Authorization: Bearer nim_YOUR_KEY
```

کلیدها پس از ورود به حساب، در [پلتفرم](https://ahoos-ai.site/services/platforme/) ساخته و باطل می‌شوند. به درخواستی که کلید نداشته باشد یا کلید آن ناشناخته یا باطل‌شده باشد، با کد وضعیت `401` پاسخ داده می‌شود.

## نمونه {#example}

با کتابخانهٔ رسمی OpenAI برای پایتون:

```python
from openai import OpenAI

client = OpenAI(base_url="https://ahoos-ai.site/services/api/v1", api_key="nim_YOUR_KEY")

response = client.chat.completions.create(
    model="nimbus-2-apex",
    messages=[{"role": "user", "content": "بازگشت (recursion) را در دو جمله توضیح بده."}],
    extra_body={"thinking_level": 5},
)
print(response.choices[0].message.content)
```

## درخواست {#request}

`POST /chat/completions` یک بدنهٔ JSON با حجم حداکثر ۱۶ مگابایت می‌پذیرد.

| فیلد | نوع | توضیح |
|---|---|---|
| `messages` | آرایه | الزامی. پیام‌های گفتگو با نقش‌های `system`، `user`، `assistant` و `tool`. آخرین پیام باید از نوع `user` یا `tool` باشد. محتوا یک رشته یا آرایه‌ای از بخش‌های متنی است. |
| `model` | رشته | اختیاری. در صورت ارسال، باید `nimbus-2-apex` باشد. |
| `stream` | بولی | پاسخ را به‌صورت رویدادهای server-sent ارسال می‌کند. پیش‌فرض `false`. |
| `max_tokens` | عدد صحیح | بیشترین طول پاسخ، از ۱۶ تا ۸۱۹۲ توکن. پیش‌فرض ۴۰۹۶. فیلد `max_completion_tokens` نیز پذیرفته می‌شود. استدلال مدل سهمیهٔ جداگانه‌ای دارد که سطح استدلال آن را تعیین می‌کند. |
| `thinking_level` | عدد صحیح | سطح استدلال، از ۱ تا ۲۰. پیش‌فرض ۵. در سطوح بالاتر، مدل پیش از پاسخ طولانی‌تر استدلال می‌کند. |
| `reasoning_effort` | رشته | جایگزین `thinking_level`: مقدار `minimal` (۱)، `low` (۳)، `medium` (۶) یا `high` (۱۲). |
| `temperature_dial` | عدد صحیح | دما، از ۱ تا ۱۰. پیش‌فرض ۵. مقادیر کمتر پاسخ‌های قابل‌پیش‌بینی‌تری می‌دهند. |
| `temperature` | عدد | جایگزین `temperature_dial`: مقدار در ۵ ضرب و گرد می‌شود (۱٫۰ برابر ۵ است). |
| `tools` | آرایه | توابعی که مدل می‌تواند فراخوانی کند، در قالب OpenAI. بخش [ابزارها](#tools) را ببینید. |
| `tool_choice` | رشته یا شیء | `auto` (پیش‌فرض)، `none`، `required` یا `{"type": "function", "function": {"name": "..."}}`. |
| `nimbus_tools` | آرایه | ابزارهایی که در سمت اهوس‌ای‌آی اجرا می‌شوند: `web_search` و `fetch_url`. بخش [جستجوی وب](#web-search) را ببینید. |
| `web_search_options` | شیء | جستجوی وب را مانند API شرکت OpenAI فعال می‌کند. محتوای آن استفاده نمی‌شود. |

سایر فیلدهای قالب OpenAI پذیرفته و نادیده گرفته می‌شوند. صدا و فایل‌هایی جز تصویر پشتیبانی نمی‌شوند.

## پاسخ {#response}

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "nimbus-2-apex",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "متن پاسخ.",
      "reasoning_content": "استدلالی که پیش از پاسخ انجام شد."
    }
  }],
  "usage": {"prompt_tokens": 120, "completion_tokens": 310, "total_tokens": 430},
  "nimbus": {"thinking_level": 5, "temperature": 5, "think_words": 160, "forced_close": false, "tokens_per_second": 28.4}
}
```

- `reasoning_content` استدلال مدل و `content` پاسخ نهایی است.
- مقدار `finish_reason` یکی از `stop`، `length` (رسیدن پاسخ به `max_tokens` یا به سقف حافظهٔ متن) یا `tool_calls` است.
- `nimbus.forced_close` زمانی `true` است که استدلال به سقف سطح خود رسیده و بسته شده باشد.

## پخش زنده {#streaming}

با `"stream": true` پاسخ به‌صورت دنباله‌ای از رویدادهای server-sent ارسال می‌شود که هر کدام یک سطر `data: {...}` است:

- `choices[0].delta.reasoning_content`: بخش بعدی استدلال.
- `choices[0].delta.content`: بخش بعدی پاسخ.
- `choices[0].delta.tool_calls`: یک فراخوانی ابزار که کامل در یک رویداد ارسال می‌شود.
- آخرین رویداد شامل `finish_reason`، `usage` و `nimbus` است و پس از آن جریان با `data: [DONE]` پایان می‌یابد.

خطایی که در میانهٔ پخش رخ دهد به این صورت ارسال می‌شود: `data: {"error": {"message": "...", "type": "..."}}`.

## ابزارها {#tools}

ابزارها از قالب فراخوانی تابع OpenAI پیروی می‌کنند. هرگاه مدل تصمیم به استفاده از ابزار بگیرد، پاسخ با `finish_reason: "tool_calls"` و یک فراخوانی در `message.tool_calls` پایان می‌یابد. تابع را اجرا کنید، پیام دستیار و یک پیام `tool` حاوی نتیجه را به گفتگو بیفزایید و درخواست را دوباره ارسال کنید:

```json
{"role": "tool", "tool_call_id": "call_...", "content": "نتیجهٔ تابع"}
```

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

## تصویر {#images}

پیام کاربر می‌تواند تصویرهایی را به‌صورت بخش‌های `image_url` قالب OpenAI داشته باشد، به‌شکل نشانی `data:` (PNG، JPEG، WebP یا GIF) یا یک نشانی `https`:

```json
{"role": "user", "content": [
  {"type": "text", "text": "این نمودار چه چیزی را نشان می‌دهد؟"},
  {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]}
```

مدل فقط متن می‌خواند. هر تصویر ابتدا با ماژول تصویر اهوس‌ای‌آی، apex-imagexo-v1، خوانده می‌شود که متن آن (با OCR، به فارسی و انگلیسی) و شکل‌هایش (مکان، اندازه و رنگ) را به یک صحنهٔ XML تبدیل می‌کند و مدل از روی همین صحنه پاسخ می‌دهد. این ماژول اسناد، تصویر صفحه، جدول، فرم، نمودار و دیاگرام را به‌خوبی می‌خواند، اما محتوای عکس‌ها، مانند چهره یا اشیا، را نمی‌بیند.

- حداکثر ۴ تصویر در هر درخواست، هر کدام حداکثر ۸ مگابایت.
- صحنه‌های تصویرهای آخرین پیام در `nimbus.images` بازگردانده می‌شوند. در نوبت‌های بعدی، به‌جای خود تصویر همین صحنه‌ها را به‌صورت متن بفرستید تا تصویر دوباره خوانده نشود.

## عامل‌ها و ابزارها {#agents}

وقتی درخواستی `tools` خود شما را همراه دارد، مدل به‌صورت عامل (agent) کار می‌کند: در هر مرحله یا یکی از ابزارهای شما را فراخوانی می‌کند یا پاسخ می‌دهد، و آرگومان‌های فراخوانی از طرح‌وارهٔ پارامترهای همان ابزار پیروی می‌کنند. برای کمک به انتخاب درست، ابزارهایی که نام‌های رایج نوشتن، ویرایش و خواندن فایل، فهرست کردن فایل‌ها و اجرای دستور دارند (مانند `Write`، `Edit`، `Read`، `Glob` و `Bash`) به مدل معرفی می‌شوند، و پوشهٔ پروژه‌ای که در پیام system نام برده شده باشد (مانند `Primary working directory: ...`) به‌عنوان محل فایل‌ها به مدل گفته می‌شود. فهرست ابزارها را به آنچه کار لازم دارد محدود کنید: فهرست طولانی حافظهٔ متن را مصرف می‌کند و انتخاب درست را دشوارتر می‌کند.

## جستجوی وب {#web-search}

با `"nimbus_tools": ["web_search", "fetch_url"]` (یا `web_search_options`) مدل می‌تواند پیش از پاسخ در وب جستجو کند و صفحه‌ها را بخواند. این ابزارها روی سرورهای اهوس‌ای‌آی اجرا می‌شوند؛ فراخوانی‌های آن‌ها به شما بازگردانده نمی‌شود و پاسخ با نتایج آن‌ها ادامه می‌یابد. هر پاسخ می‌تواند تا شش مرحله از این نوع داشته باشد.

- در حالت پخش زنده، هر مرحله در فیلد `nimbus_tool` گزارش می‌شود: `{"id", "name", "arguments", "status"}`، که `status` یکی از `running`، `done` یا `error` است. جستجوی تمام‌شده فهرست `results` (عنوان، نشانی و خلاصه) را نیز دارد.
- در پاسخ غیرزنده، مراحل انجام‌شده در `nimbus.tools` فهرست می‌شوند.

عبارت‌های جستجو به موتورهای جستجوی عمومی ارسال می‌شوند و صفحه‌ها از سایت‌های خودشان دریافت می‌شوند.

## خطاها {#errors}

خطاها در قالب OpenAI بازگردانده می‌شوند: `{"error": {"message": "...", "type": "..."}}`.

| کد وضعیت | نوع | معنا |
|---|---|---|
| 400 | `invalid_request_error` | بدنه JSON معتبر نیست، پیامی ندارد، یا آخرین پیام آن از نوع `user` یا `tool` نیست. |
| 401 | `authentication_error` | کلید ارسال نشده، ناشناخته یا باطل‌شده است. |
| 404 | `invalid_request_error` | مسیر یا مدل ناشناخته است. |
| 405 | `invalid_request_error` | روش درخواست مجاز نیست. |
| 413 | `invalid_request_error` | حجم بدنه بیش از ۱۶ مگابایت است. |
| 429 | `rate_limit_error` | سقف مصرف کلید در این دوره تمام شده است. خطا شامل `used`، `limit` و `period` است. |
| 502، 503 | `engine_error`، `engine_unavailable` | مدل نتوانست پاسخ دهد. بعداً دوباره تلاش کنید. |

## حافظهٔ متن و زمان پاسخ {#context}

- هر درخواست در مجموع می‌تواند تا ۴۰٬۹۶۰ توکن استفاده کند: گفتگو، تعریف ابزارها، استدلال و پاسخ. اگر طولانی‌تر باشد، ابتدا توضیحات ابزارها کوتاه می‌شوند و سپس قدیمی‌ترین نوبت‌ها کنار گذاشته می‌شوند؛ اگر آخرین نوبت به‌تنهایی جا نشود، درخواست با خطا پایان می‌یابد.
- مدل هنگام نیاز راه‌اندازی می‌شود. پس از مدتی بدون درخواست، نخستین پاسخ ممکن است تا دو دقیقه طول بکشد.
- درخواست‌ها یکی‌یکی پاسخ داده می‌شوند و بقیه در نوبت می‌مانند.
- درخواست طولانی ممکن است تا یک دقیقه پیش از نخستین توکن زمان ببرد. در این مدت، در پاسخ زنده هر چند ثانیه یک سطر توضیحی (`: keepalive`) ارسال می‌شود که کلاینت‌های SSE آن را نادیده می‌گیرند.