اولین درخواست

در این بخش یاد خواهید گرفت که چگونه اولین درخواست خود را به سرویس هوش مصنوعی خاتش ارسال کنید. این راهنما شامل مراحل گام به گام برای تنظیم کلید دسترسی و ارسال درخواست اولیه است.

روش‌های ارسال درخواست

برای ارسال درخواست به سرویس API خاتش، دو روش اصلی در اختیار دارید:

۱. استفاده از درخواست‌های مستقیم HTTP

می‌توانید با استفاده از ابزارهای استاندارد HTTP مانندfetch()،axios،curlیا هر کتابخانه HTTP دیگری، مستقیماً باAPI خاتش ارتباط برقرار کنید.

در این روش، شما باید ساختار درخواست JSON و هدرهای مورد نیاز را خودتان تنظیم کنید.

۲. استفاده از کتابخانه OpenAI (پیشنهادی)

می‌توانید از کتابخانه رسمی OpenAI درPython،JavaScript یاTypeScriptاستفاده کنید. تنها کاری که باید انجام دهید این است کهbase_url (در پایتون) یاbaseURL (در جاوا اسکریپت) را به آدرس سرویس خاتش تغییر دهید.

base_url="https://ai.khatash.com/api/v1"

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

تولید متن

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

تفاوت بین completion و chat/completions

سرویس خاتش دو نوع endpoint اصلی برای تولید متن ارائه می‌دهد:

/v1/chat/completions (پیشنهادی)

این endpoint برای گفتگوهای چندپیامه طراحی شده و امکان تعریف نقش‌های مختلف (system, user, assistant) را فراهم می‌کند. برای اکثر کاربردها از جمله چت‌بات‌ها، دستیار‌های هوشمند و برنامه‌های تعاملی مناسب است.

/v1/completions (قدیمی)

این endpoint برای تکمیل متن ساده طراحی شده و تنها یک رشته متنی دریافت می‌کند. عمدتاً برای مدل‌های قدیمی‌تر استفاده می‌شود و برای کاربردهای جدید توصیه نمی‌شود.

نمونه عملی تولید متن

ساده‌ترین نوع درخواست برای تولید متن است. در این نمونه، از مدل می‌خواهیم که یک متن خلاقانه تولید کند.

GNU Bashtext_generation.sh
curl -L -X POST 'https://ai.khatash.com/api/v1/chat/completions/' \  -H 'Authorization: Bearer $KHATASH_API_KEY' \  -H 'Content-Type: application/json' \  -d '{    "model": "openai/gpt-4o-mini",    "messages": [      {        "role": "user",        "content": "لطفاً یک قصه کوتاه درباره یک ماجراجوی فضایی بنویس."      }    ],    "max_tokens": 500,    "temperature": 0.7  }'

نکات مهم:

  • حتماً کلید API خود را در متغیر محیطی KHATASH_API_KEY قرار دهید
  • پارامتر max_tokens حداکثر طول پاسخ را کنترل می‌کند
  • پارامتر temperature میزان خلاقیت مدل را تنظیم می‌کند (۰ تا ۱)

ارسال تصویر به دو روش در بینایی ماشین (Vision)

مدل‌های بینایی خاتش قابلیت تحلیل و درک تصاویر را دارند. شما می‌توانید تصویر را به دو روش ارسال کنید: ۱) با URL مستقیمِ تصویر، ۲) به صورت Base64 (به شکل data URL). اگر تصویر شما عمومی است از روش URL استفاده کنید؛ اگر فایل محلی/خصوصی دارید، روش Base64 مناسب‌تر است. در هر دو روش، مقدار نهایی در فیلدimage_url.url قرار می‌گیرد.

ارسال تصویر با آدرس URL (تصویر عمومی)

اگر تصویر شما به‌صورت عمومی قابل دسترس است، کافی‌ست URL مستقیم آن را در فیلدimage_url.url قرار دهید. این روش ساده و سبک است و برای اکثر سناریوها پیشنهاد می‌شود.

GNU Bashvision_url.sh
curl -L -X POST 'https://ai.khatash.com/api/v1/chat/completions/' \  -H 'Authorization: Bearer $KHATASH_API_KEY' \  -H 'Content-Type: application/json' \  -d '{    "model": "openai/gpt-4o-mini",    "messages": [      {        "role": "user",        "content": [          {            "type": "text",            "text": "این تصویر چه چیزی را نشان می‌دهد؟ لطفاً توضیح مفصلی ارائه دهید."          },          {            "type": "image_url",            "image_url": {              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"            }          }        ]      }    ]  }'

نکات:

  • URL باید قابل دسترس عمومی باشد و بهتر است از HTTPS استفاده شود.
  • آدرس را مستقیماً به خود فایل تصویر اشاره دهید و از لینک‌های موقت یا نیازمند ورود پرهیز کنید.
  • مقدار image_url.url می‌تواند همین URL مستقیم باشد.

ارسال تصویر به صورت Base64 (فایل محلی/خصوصی)

برای فایل‌های محلی یا تصاویر خصوصی که عمومی نیستند، تصویر را به Base64 تبدیل کنید و آن را به شکلdata URL (مثل data:image/jpeg;base64,...) در فیلدimage_url.url قرار دهید.

Pythonvision_base64.py
from openai import OpenAIimport osimport base64def encode_image_to_base64(image_path):    with open(image_path, "rb") as image_file:        return base64.b64encode(image_file.read()).decode('utf-8')client = OpenAI(    api_key=os.getenv("KHATASH_API_KEY"),    base_url="https://ai.khatash.com/api/v1",)# تصویر را کدگذاری کنیدimage_path = "path/to/your/image.jpg"base64_image = encode_image_to_base64(image_path)data_url = f"data:image/jpeg;base64,{base64_image}"response = client.chat.completions.create(    model="openai/gpt-4o-mini",    messages=[        {            "role": "user",            "content": [                {                    "type": "text",                    "text": "این تصویر چه چیزی را نشان می‌دهد؟"                },                {                    "type": "image_url",                    "image_url": {                        "url": data_url                    }                }            ]        }    ])print(response.choices[0].message.content)

نکات:

  • پیشوند صحیح data URL را با نوع فایل درست (مثلاً image/png) قرار دهید.
  • حجم رشته Base64 نسبت به فایل اصلی کمی بزرگ‌تر است؛ برای تصاویر کوچک یا متوسط مناسب‌تر است.
  • این روش برای فایل‌های محلی/خصوصی یا زمانی که دسترسی عمومی ممکن نیست کاربردی است.

فرمت‌های پشتیبانی شده:

image/pngimage/jpegimage/webpimage/gif