مرجع API

Embeddings

متن را برای جست‌وجوی معنایی و مقایسهٔ شباهت به بردار تبدیل کنید. مدلی را انتخاب کنید که embedding را پشتیبانی می‌کند و ابعاد بردارها را در ایندکس خودتان یکسان نگه دارید.

روند کار

01ساخت embedding برای یک یا چند ورودی

روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.

ساخت embedding برای یک یا چند ورودی

POST/v1/embeddings

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتAPI key پروژه یا JWT کاربر

Responseresponse مستقیم با قالب OpenAI

نوع محتواapplication/json

پارامترها

این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`Idempotency-Key`	Header	string	اختیاری	پشتیبانی می‌شود	کلید تکرار امن برای یک اجرا؛ اگر دوباره فرستاده شود، همان نتیجهٔ اول برمی‌گردد.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`dimensions`	Body	integer	اختیاری	مشروط	طول بردار خروجی. فقط برای مدلی پذیرفته می‌شود که همین طول را اعلام کرده باشد؛ هر مقدار دیگری پیش از تماس با ارائه‌دهنده رد می‌شود.
`encoding_format`	Body	string	اختیاری	پشتیبانی می‌شود	`float` یا `base64`.
`input`	Body	string \| array<value>	الزامی	پشتیبانی می‌شود	یک رشته، فهرستی از رشته‌ها، آرایه‌ای از tokenها یا فهرستی از چنین آرایه‌هایی. تعداد موارد و تعداد tokenها در هر مورد و در کل request محدود است.
`model`	Body	string	الزامی	پشتیبانی می‌شود	شناسهٔ عمومی مدل embedding.
`user`	Body	string	اختیاری	پشتیبانی می‌شود	شناسهٔ کاربر برای پایش سوءاستفاده نزد ارائه‌دهنده.

فیلدهای مشروط فقط وقتی کار می‌کنند که مدل و مسیر ارائه‌دهنده از آن‌ها پشتیبانی کنند.

Request

curl -X POST 'https://api.mahvashai.ir/v1/embeddings' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "<embedding-model-from-GET-/v1/models>",
  "input": "A short document to embed."
}'

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.012,
        -0.021,
        0.037
      ]
    }
  ],
  "model": "<embedding-model-id>",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
402	موجودی برای پرداخت هزینه کافی نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
409	تداخل در وضعیت یا idempotency.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.
502	سرویس ارائه‌دهنده با خطا مواجه شد.
503	یکی از سرویس‌های موردنیاز موقتاً در دسترس نیست.