ورودی‌ها (چندرسانه‌ای)

سرویس AI API خاتش، که به‌عنوان یک لایهٔ میانی روی OpenRouter عمل می‌کند، از ورودی‌های چندرسانه‌ای مانند تصویر، PDF، صوت و ویدیو پشتیبانی می‌کند. همهٔ این ورودی‌ها از طریق همان اندپوینت /chat/completions ارسال می‌شوند.

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

خلاصهٔ امکانات
  • تصویر: تحلیل، توصیف، OCR و استخراج اطلاعات از تصویر.
  • تولید تصویر: ایجاد تصویر از روی متن (بسته به مدل پشتیبان).
  • PDF: پردازش گزارش‌ها، مقالات و فایل‌های چندصفحه‌ای.
  • صوت: پیاده‌سازی، تحلیل و پردازش سیگنال صوتی.
  • ویدیو: توصیف، استخراج رویدادها و تحلیل محتوای ویدیویی (برای مدل‌های سازگار).

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

همهٔ ورودی‌های چندرسانه‌ای از طریق آرایهٔ messages و در فیلد content ارسال می‌شوند. هر آیتم در این آرایه یک آبجکت با فیلد type است که نوع محتوا (متن، تصویر، فایل، صوت، ویدیو و ...) را مشخص می‌کند.

content-types.json
{  "model": "openai/gpt-4o-mini",  "messages": [    {      "role": "user",      "content": [        {          "type": "text",          "text": "خلاصهٔ کوتاهی از این محتوا بده."        },        {          "type": "image_url",          "image_url": {            "url": "https://example.com/image.jpg"          }        },        {          "type": "file",          "file": {            "url": "https://example.com/document.pdf",            "mime_type": "application/pdf"          }        },        {          "type": "input_audio",          "input_audio": {            "format": "mp3",            "data": "<BASE64_AUDIO_DATA>"          }        },        {          "type": "video_url",          "video_url": {            "url": "https://www.youtube.com/watch?v=..."          }        }      ]    }  ]}

نمونه‌های عملی (HTTP و SDK)

در ادامه چند نمونهٔ متداول برای ارسال ورودی چندرسانه‌ای به اندپوینت /chat/completions روی دامنهٔ ai.khatash.com را مشاهده می‌کنید.

curl-multimodal.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://example.com/cat.png" } }      ]    }  ]}'
multimodal.py
from openai import OpenAIimport osclient = OpenAI(    api_key=os.getenv("KHATASH_API_KEY"),    base_url="https://ai.khatash.com/api/v1",)response = client.chat.completions.create(    model="openai/gpt-4o-mini",    messages=[        {            "role": "user",            "content": [                {"type": "text", "text": "خلاصه‌ای از این فایل PDF بده"},                {                    "type": "file",                    "file": {                        "url": "https://example.com/report.pdf",                        "mime_type": "application/pdf",                    },                },            ],        }    ],)print(response.choices[0].message.content)

انواع ورودی و فرمت‌ها

۱. تصویر (Images)

برای ارسال تصویر، از نوع image_url استفاده کنید. مقدار url می‌تواند یک آدرس عمومی یا دادهٔ base64 باشد.

  • URL عمومی: مناسب فایل‌هایی که روی اینترنت یا فضای ابری در دسترس هستند.
  • Base64: برای فایل‌های محلی یا محتوای خصوصی که نمی‌خواهید عمومی کنید.

۲. تولید تصویر (Image Generation)

برخی مدل‌ها به‌جای تحلیل تصویر، تصویر جدید تولید می‌کنند. در این حالت، همچنان از اندپوینت /chat/completions استفاده می‌کنید و پاسخ مدل حاوی لینک یا دادهٔ تصویر خروجی خواهد بود.

۳. PDF و سایر فایل‌ها

برای ارسال PDF از نوع file استفاده کنید. سیستم خاتش و OpenRouter متن را استخراج کرده و آن را برای مدل آماده می‌کنند.

پیشنهاد می‌شود تا حد امکان از URLهای قابل‌دسترسی و با mime_type صحیح (مثلاً application/pdf) استفاده کنید.

۴. صوت (Audio)

برای ورودی صوتی از نوع input_audio استفاده کنید. دادهٔ صوتی باید به صورت base64 ارسال شود و فرمت (مثلاً mp3 یا wav) در فیلد format مشخص گردد.

۵. ویدیو (Video)

برای ویدیو از نوع video_url استفاده کنید. بسته به ارائه‌دهنده، ممکن است فقط برخی نوع لینک‌ها (مثلاً لینک یوتیوب برای مدل‌های Gemini) پشتیبانی شوند.

مثال: استفاده از Base64 برای فایل محلی

زمانی که نمی‌توانید فایل را به‌صورت عمومی در دسترس قرار دهید، می‌توانید آن را در سمت کلاینت به base64 تبدیل کرده و داخل بدنهٔ درخواست ارسال کنید:

image-base64.json
{  "type": "image_url",  "image_url": {    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."  }}

سازگاری مدل‌ها با ورودی چندرسانه‌ای

همهٔ مدل‌ها از همهٔ انواع ورودی پشتیبانی نمی‌کنند. لایهٔ خاتش روی OpenRouter به‌صورت خودکار بررسی می‌کند که مدل انتخابی با نوع محتوای ارسال‌شده سازگار باشد.

  • مدل‌های بینایی: برای پردازش تصویر الزامی هستند.
  • مدل‌های فایل‌محور: از پردازش PDF و اسناد پشتیبانی می‌کنند.
  • مدل‌های صوتی: برای ورودی صوتی مورد نیاز هستند.
  • مدل‌های ویدیویی: برای تحلیل ویدیو لازم‌اند و معمولاً فقط توسط برخی ارائه‌دهندگان خاص ارائه می‌شوند.

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

نکات کارایی و هزینه

استفاده از ورودی‌های چندرسانه‌ای معمولاً توکن بیشتری در سمت مدل مصرف می‌کند و ممکن است هزینهٔ هر درخواست را افزایش دهد. برای کنترل هزینه:

  • فقط بخش‌های ضروری فایل (مثلاً صفحات مهم PDF) را ارسال کنید.
  • تصاویر را قبل از ارسال، تا حد امکان فشرده و کوچک کنید.
  • برای ویدیو، در صورت امکان از برش‌های کوتاه یا لینک‌هایی با محتوای مرتبط استفاده کنید.

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