رفتن به محتوا

پشتیبانی از تصاویر

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

مستندات

دو راه فرستادن تصویر

Base64 را توصیه می‌کنیم: فایل داخل خود درخواست سفر می‌کند، پس هیچ چیزی هنگام گرفتنش شکست نمی‌خورد. URL هم کار می‌کند و درگاه آن را برای شما دانلود می‌کند، اما باید عمومی و در دسترس باشد و یک مرحلهٔ دانلود به هر درخواست اضافه می‌کند.

برای فرستادن تصویر همراه با پیام کاربر، تصویر را در قالب data URI (روش پیشنهادی) یا به صورت یک نشانی https بفرستید:

این صفحه دربارهٔ فرستادن تصویر به مدل است، برای اینکه مدل تصویر را ببیند و توصیف کند. اگر می‌خواهید مدل از روی متن تصویر بسازد، صفحهٔ تولید تصویر با AI جای درست است، و برای فرستادن یک سند PDF به ورودی فایل بروید.

تبدیل تصویر و ارسال

کل کار دو خط است: فایل را بخوانید، به Base64 تبدیل کنید، و رشتهٔ حاصل را با پیشوند data:image/png;base64, بفرستید. این نمونه‌ها همان‌طور که هستند اجرا می‌شوند، فقط کلید و نام فایل را عوض کنید.

IMAGE=$(base64 -w0 image.png) curl https://api-ai.hibanacloud.ir/v1/chat/completions \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-5-nano",    "messages": [{      "role": "user",      "content": [        {"type": "text", "text": "در یک جمله بگو در تصویر چه می‌بینی."},        {"type": "image_url", "image_url": {"url": "data:image/png;base64,'"$IMAGE"'"}}      ]    }],    "max_completion_tokens": 2000,    "reasoning_effort": "low"  }'

پیشوند data URI باید با فرمت واقعی فایل بخواند: برای JPEG data:image/jpeg;base64, و برای WebP data:image/webp;base64,.

ساختار content

در یک درخواست معمولی، content یک رشته است. برای فرستادن تصویر، به آرایه‌ای از «بخش»ها تبدیل می‌شود که هرکدام یک type دارند:

بخش‌های آرایهٔ content
نوع بخشفیلد دادهتوضیح
type: "text"textمتن پیام کاربر. همان چیزی که در حالت بدون تصویر یک رشتهٔ ساده بود.
type: "image_url"image_url.urlتصویر: یک data URI با Base64 (پیشنهادی) یا یک نشانی https که درگاه خودش آن را دانلود می‌کند.

بقیهٔ درخواست تغییری نمی‌کند: همان model، همان messages، همان پارامترهای Chat Completions.

درخواست کامل

POST https://api-ai.hibanacloud.ir/v1/chat/completions Headers:  Content-Type: application/json  Authorization: Bearer YOUR_API_TOKEN Body (JSON):{  "model": "gpt-5-nano",  "messages": [    {      "role": "user",      "content": [        { "type": "text", "text": "این تصویر را توصیف کن" },        {          "type": "image_url",          "image_url": {            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."          }        }      ]    }  ],  "max_tokens": 4096}

یک نمونهٔ واقعی

همان درخواست بالا، اجرا شده روی تصویر زیر. پاسخ دقیقاً همان چیزی است که مدل برگرداند:

نمای از بالای یک میز چوبی با یک فنجان قرمز، یک عینک با قاب مشکی، یک دفترچهٔ باز و یک مداد.
تصویر ورودی. خودش با همین سرویس ساخته شده است.

پاسخ مدل

روی یک میز چوبی یک دفترچه باز با کاغذهای سفید، یک جفت عینک، یک مداد و یک فنجان قرمز دیده می‌شود.

مدل مداد را هم نام برده است، در حالی که در متن ساخت تصویر خواسته نشده بود. تصویر ورودی ۴۱۷ توکن از سهم درخواست مصرف کرد.

نکات

  • فرمت Base64 باید به صورت data URI باشد: data:image/jpeg;base64,...
  • فرمت‌های پشتیبانی شده: JPEG, PNG, GIF, WebP
  • تصاویر درون آرایه‌ی content به عنوان اشیاء image_url ارسال می‌شوند
  • مدل‌های Vision قادر به تحلیل و توصیف تصاویر هستند (مانند: gpt-5-nano, claude-sonnet-4-5)

Base64 حجم فایل را حدود یک‌سوم بزرگ‌تر می‌کند و همهٔ آن در بدنهٔ درخواست می‌رود، پس تصویر را قبل از ارسال کوچک کنید. اگر مدلی که انتخاب کرده‌اید Vision نباشد، پاسخ خطا خواهد بود، فهرست مدل‌ها در لیست مدل‌ها است و معنی کدهای خطا در مدیریت خطاها.