ورودی تصویر و فایل (Vision)

مدل‌های چندرسانه‌ای تصویر و فایل را در همان آرایهٔ messages می‌گیرند. به‌جای رشته، content یک آرایه از بخش‌ها می‌شود: بخش‌های text، image_url و file. این همان فرمت OpenAI است و بدون تغییر به provider می‌رسد.

کدام مدل‌ها

• تصویر: نشان vision در صفحهٔ مدل‌ها؛ در GET /v1/models یعنی "image" در input_modalities. بیش از ۲۵۰ مدل کاتالوگ این قابلیت را دارند.
• فایل (PDF): نشان files؛ معادل "file" در input_modalities. مدل‌های اصلی OpenAI، Anthropic و Google پشتیبانی می‌کنند.

اگر تصویر را به مدلی بفرستی که پشتیبانی نمی‌کند، provider معمولاً 400 برمی‌گرداند و رزرو آزاد می‌شود؛ گاهی هم مدل بی‌صدا تصویر را نادیده می‌گیرد و فقط به متن جواب می‌دهد. برای کار تولیدی مدل را از روی نشان انتخاب کن نه از روی نام.

تصویر با URL

from openai import OpenAI

client = OpenAI(base_url="https://api.uttapen.ir/v1", api_key="sk-up-...")

resp = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "این فاکتور چه اقلامی دارد؟ به‌صورت فهرست بنویس."},
            {"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg", "detail": "high"}},
        ],
    }],
    max_tokens=500,
)
print(resp.choices[0].message.content)

URL باید از اینترنت عمومی قابل دانلود باشد، چون provider خودش آن را می‌گیرد. آدرس‌های داخل شبکهٔ شرکت یا پشت لاگین کار نمی‌کنند؛ برای آن‌ها data URI بفرست. detail (low، high، auto) را همهٔ providerها رعایت نمی‌کنند ولی برای OpenAI روی هزینه اثر دارد.

تصویر با data URI (base64)

import base64, pathlib

data = base64.b64encode(pathlib.Path("invoice.jpg").read_bytes()).decode()

resp = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "مبلغ کل و تاریخ این فاکتور را استخراج کن."},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{data}"}},
        ],
    }],
)

فرمت‌های رایج image/jpeg، image/png، image/webp و image/gif هستند. قبل از ارسال، تصویر را به عرض ۱۰۰۰ تا ۱۵۰۰ پیکسل کوچک کن؛ برای خواندن متن فاکتور و فرم کافی است و توکن کمتری مصرف می‌کند.

فایل PDF

pdf = base64.b64encode(pathlib.Path("contract.pdf").read_bytes()).decode()

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "بندهای مربوط به فسخ قرارداد را خلاصه کن."},
            {"type": "file", "file": {"filename": "contract.pdf", "file_data": f"data:application/pdf;base64,{pdf}"}},
        ],
    }],
    max_tokens=1500,
)

filename را بده؛ بعضی providerها از پسوند آن نوع فایل را تشخیص می‌دهند. PDF اسکن‌شده (تصویری) هم برای مدل‌هایی که خودشان OCR دارند کار می‌کند ولی گران‌تر از PDF متنی است. اگر سند بلند است، اول با یک کتابخانهٔ PDF متن را بیرون بکش و به‌عنوان text بفرست؛ هم ارزان‌تر است هم قابل کنترل‌تر.

محدودیت‌ها

• حداکثر بدنهٔ درخواست ۲۰ مگابایت است؛ بیشتر از آن 413 request_too_large می‌گیری و درخواست به provider نمی‌رود. base64 حجم را حدود ۳۳٪ بزرگ می‌کند، پس فایل خام حداکثر حدود ۱۵ مگابایت.
• providerها سقف خودشان را دارند (تعداد تصویر در هر پیام، ابعاد، تعداد صفحهٔ PDF). خطای آن‌ها با همان status عبور می‌کند.
• پاسخ مدل به تصویر همان content متنی است؛ برای تولید تصویر مدل‌های با نشان image out را ببین. آن‌ها فعلاً از مسیر chat/completions و با فیلد modalities کار می‌کنند، نه /v1/images.

هزینه

هزینهٔ تصویر بسته به provider سه شکل دارد و در همهٔ حالت‌ها مصرفی که خود مدل برای همین درخواست گزارش می‌دهد مبنای شارژ است:

1. توکنی — تصویر به تعدادی توکن ورودی تبدیل می‌شود (OpenAI، Google). با قیمت prompt همان مدل حساب می‌شود.
2. به‌ازای هر تصویر — بعضی مدل‌ها قیمت جدای image دارند. در صفحهٔ مدل به‌صورت «تومان / تصویر» نشان داده می‌شود و در uttapen_pricing.image_toman هست.
3. فایل — PDF معمولاً به‌ازای صفحه به توکن تبدیل می‌شود.

برای رزرو قبل از ارسال، هر تصویر معادل ۱۰۰۰ توکن ورودی (یا قیمت image مدل اگر داشته باشد) و هر بخش inline به نسبت حجمش (حدود یک توکن به‌ازای هر ۴ بایت) برآورد می‌شود. این رزرو موقت است و تسویه با مبلغ واقعی انجام می‌شود؛ ولی یعنی برای فرستادن یک PDF ده مگابایتی باید موجودی معنی‌داری داشته باشی وگرنه 402 می‌گیری. جزئیات در قیمت‌گذاری.