ورودی تصویر (Images)

سرویس AI API خاتش، که روی OpenRouter ساخته شده است، امکان ارسال تصویر به مدل‌های چندرسانه‌ای (vision) را فراهم می‌کند. این مدل‌ها می‌توانند تصویر را توصیف کنند، متن داخل آن را استخراج کنند (OCR) و روی اشیاء و صحنهٔ تصویر استدلال انجام دهند.

همهٔ این قابلیت‌ها از طریق اندپوینت واحد /api/v1/chat/completions روی دامنهٔ ai.khatash.com در دسترس هستند و تصویر به‌صورت یک آیتم image_url در آرایهٔ content قرار می‌گیرد.

ویژگی‌ها و ساختار ورودی

درخواست‌های شامل تصویر به‌صورت پیام‌های چندبخشی ارسال می‌شوند؛ متن و تصویر در آرایهٔ content کنار هم قرار می‌گیرند. توصیه می‌شود ابتدا متن (پرامپت) را بفرستید و بعد تصاویر را اضافه کنید تا پارسر محتوا و مدل بهتر متوجه منظور شما شود. اگر لازم است تصویر قبل از متن باشد، می‌توانید آن را در پیام نقش system قرار دهید.

می‌توانید چند تصویر را در یک درخواست ارسال کنید؛ کافی است برای هر تصویر یک آیتم image_url جداگانه در آرایهٔ content اضافه کنید. تعداد مجاز تصاویر در هر درخواست به ارائه‌دهنده و مدل بستگی دارد.

image-input.json
{  "model": "google/gemini-2.0-flash-001",  "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 در برابر Base64

خاتش (و OpenRouter) دو روش اصلی برای ارسال تصویر پشتیبانی می‌کند:

  • URL: مناسب تصاویر عمومی و میزبانی‌شده در وب؛ نیازی به تبدیل به base64 ندارد و بدنهٔ درخواست را کوچک‌تر نگه می‌دارد.
  • Base64: مناسب فایل‌های محلی یا تصاویری که نمی‌خواهید به‌صورت عمومی در دسترس باشند.
image-url.py
import osimport jsonimport requestsurl = "https://ai.khatash.com/api/v1/chat/completions/"headers = {    "Authorization": f"Bearer {os.getenv('KHATASH_API_KEY')}",    "Content-Type": "application/json",}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"                },            },        ],    }]payload = {    "model": "google/gemini-2.0-flash-001",    "messages": messages,}response = requests.post(url, headers=headers, json=payload)print(json.dumps(response.json(), ensure_ascii=False, indent=2))

ارسال تصویر محلی با Base64 (پایتون)

برای تصاویر ذخیره‌شده روی دیسک یا منابع خصوصی، ابتدا فایل را به base64 تبدیل کنید و سپس آن را به‌صورت data URL در فیلد url قرار دهید. پیشوند باید با نوع فایل مطابقت داشته باشد، مانند data:image/jpeg;base64,.

image-base64.py
import osimport jsonimport base64from pathlib import Pathimport requestsdef encode_image_to_base64(image_path: str) -> str:    return base64.b64encode(Path(image_path).read_bytes()).decode("utf-8")url = "https://ai.khatash.com/api/v1/chat/completions/"headers = {    "Authorization": f"Bearer {os.getenv('KHATASH_API_KEY')}",    "Content-Type": "application/json",}image_path = "path/to/your/image.jpg"base64_image = encode_image_to_base64(image_path)data_url = f"data:image/jpeg;base64,{base64_image}"messages = [    {        "role": "user",        "content": [            {                "type": "text",                "text": "در این تصویر چه خبر است؟",            },            {                "type": "image_url",                "image_url": {                    "url": data_url,                },            },        ],    }]payload = {    "model": "google/gemini-2.0-flash-001",    "messages": messages,}response = requests.post(url, headers=headers, json=payload)print(json.dumps(response.json(), ensure_ascii=False, indent=2))

نکات انتخاب مدل و کارایی

  • برای استفاده از تصویر، مدلی را انتخاب کنید که در صفحهٔ «مدل‌ها» به‌عنوان مدل بینایی معرفی شده باشد.
  • تصاویر بزرگ را قبل از ارسال تا حد امکان فشرده و کوچک کنید تا هزینه و زمان پردازش کاهش یابد.
  • در صورت نیاز به پاسخ‌های تحلیلی‌تر (مثلاً استدلال روی نمودارها)، از مدل‌های قوی‌تر استفاده کنید.