پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

بینایی (ورودی تصویر)

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

برای تولید تصاویر، به راهنمای تولید تصویر مراجعه کنید .

فهرست مطالب

نقاط پایانی API
روش‌های ورودی تصویر
چک‌لیست طراحی وظیفه بینایی
ارائه شناسه فایل تصویر
ارائه URLهای تصویر
- استفاده از API تکمیل گفتگو
- استفاده از API پاسخ‌ها
ارائه تصاویر کدگذاری شده Base64
- استفاده از API تکمیل گفتگو
- استفاده از API پاسخ‌ها
چندین تصویر
مدل‌های پیشنهادی بینایی
قابلیت‌های تصویری مختص Gemini
Gemini Robotics-ER: بینایی برای رباتیک فیزیکی
محاسبه هزینه‌ها

نقاط پایانی API

AvalAI از قابلیت‌های بینایی از طریق دو نقطه پایانی API پشتیبانی می‌کند:

API پاسخ‌ها (v1/responses) - گزینه پیشنهادی برای workflowهای چندوجهی جدید که به state، ابزارها، خروجی ساختاریافته یا مسیر مهاجرت از Responses متنی نیاز دارند.
API تکمیل گفتگو (v1/chat/completions) - برای integrationهای چت موجود و routeهای ارائه‌دهنده‌ای که vision را فقط از طریق Chat Completions ارائه می‌کنند نگه دارید.

هر دو endpoint می‌توانند ورودی تصویر بگیرند، اما پشتیبانی دقیق به مدل، route ارائه‌دهنده و تنظیمات حساب بستگی دارد. ترکیب endpoint و مدل نهایی را قبل از production تست کنید.

مدل‌های پیشنهادی بینایی

برای برنامه‌های چندوجهی جدید، از خانواده مدل‌های جدید استفاده کنید:

OpenAI: gpt-5.5 برای درک تصویر پرچم‌دار، استدلال بصری، استفاده از ابزار و گردش‌کارهای چندوجهی با زمینه طولانی؛ gpt-5.4، gpt-5.4-mini و gpt-5.4-nano برای رده‌های کم‌هزینه‌تر.
Google/Gemini: gemini-3.5-flash برای استدلال چندوجهی Flash پرچم‌دار فعلی، gemini-3.1-pro-preview برای استدلال پیشرفته کلاس Pro، gemini-3.1-flash-lite برای وظایف بینایی پرترافیک و gemini-2.5-flash برای بارهای کاری قدیمی سریع.
Anthropic: claude-opus-4-7، claude-opus-4-6 و claude-sonnet-4-6 برای تحلیل تصویر و درک اسناد/اسکرین‌شات‌ها.
Z.AI: glm-5v-turbo برای وظایف کارآمد بینایی-زبان، همراه با glm-5.1 برای گردش‌کارهای استدلالی متن‌محور.
Alibaba/Qwen: خانواده‌های Qwen VL همچنان برای OCR، پرسش‌وپاسخ تصویری و درک تصویر چندزبانه کاربردی هستند؛ اگر وظیفه به ورودی تصویر نیاز ندارد، از مدل‌های متنی فعلی qwen3.7 یا qwen3.6 استفاده کنید.

روش‌های ورودی تصویر

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

با ارائه یک URL کاملا واجد شرایط به یک فایل تصویری.
با ارائه یک تصویر به عنوان یک URL داده کدگذاری شده Base64.
با آپلود تصویر در Files API و ارسال file_id آن به Responses API به‌عنوان یک input_image.

برای صفحه‌های سند، اسلایدها، فرم‌ها و فایل‌های دارای نمودار از ورودی‌های فایل PDF استفاده کنید. ورودی PDF در مدل‌های دارای قابلیت بینایی به‌صورت متن استخراج‌شده همراه تصویر صفحه‌ها پردازش می‌شود؛ تصویرها و نمودارهای embedded در سندهای غیر PDF حفظ نمی‌شوند، مگر اینکه ابتدا فایل را به PDF تبدیل کنید.

چک‌لیست طراحی وظیفه بینایی

راهنمای vision در OpenAI تصویر را ورودی typed مدل می‌داند، نه یک فایل ضمیمه عمومی. برای workflowهای production در AvalAI، پیش از ارسال تصویر قرارداد task را روشن کنید:

Carrier را آگاهانه انتخاب کنید: برای تصویرهای موقت وب از URL عمومی، برای تصویرهای محلی از Base64 data URL، وقتی ذخیره‌سازی و reuse فایل فعال است از file_id، و برای سندهای صفحه‌محور از input_file/PDF استفاده کنید.
وقتی هزینه یا دقت مهم است detail را صریح کنید: برای classification یا caption سریع از low، برای متن کوچک، chart، screenshot رابط کاربری و جزئیات شیء از high، و فقط در routeهای پشتیبانی‌شده برای تحلیل فضایی متراکم از original استفاده کنید.
ورودی چندتصویری را label کنید: به مدل بگویید هر تصویر چه چیزی را نشان می‌دهد، ترتیب را حفظ کنید و مقایسه را با labelهای صریح مثل «تصویر A» و «تصویر B» بخواهید.
evidence و uncertainty بخواهید: متن قابل مشاهده، اشیای مشاهده‌شده یا یادداشت کوتاه confidence را درخواست کنید؛ از مدل نخواهید metadata پنهان، اندازه‌گیری دقیق یا هویت را حدس بزند مگر اینکه برنامه شما آن evidence را فراهم کرده باشد.
برای کار پایین‌دست schema استفاده کنید: وقتی UI، database یا automation به fieldهای دقیق نیاز دارد، vision را با Structured Outputs ترکیب کنید.
قبل از upload داده حساس را redact کنید: secretها، چهره‌ها، شماره حساب، metadata مکانی یا screenshotهای خصوصی غیرضروری را حذف کنید.

ارائه شناسه فایل تصویر

وقتی ذخیره‌سازی فایل فعال است و می‌خواهید تصویر را یک بار آپلود کنید، در چند درخواست به آن ارجاع دهید یا از ارسال مکرر رشته Base64 بزرگ جلوگیری کنید، از شناسه فایل استفاده کنید. برای ورودی تصویر، فایل را با purpose: "vision" آپلود کنید و سپس شناسه برگشتی را در آیتم input_image در /v1/responses قرار دهید. اگر ذخیره‌سازی فایل برای حساب یا endpoint شما فعال نیست، از URL تصویر یا data URL مبتنی بر Base64 استفاده کنید.

PythonJavaScriptBash

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

file = client.files.create(
    file=open("screenshot.png", "rb"),
    purpose="vision",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "مشکل UI را در این اسکرین‌شات توضیح بده.",
                },
                {"type": "input_image", "file_id": file.id},
            ],
        }
    ],
)

print(response.output_text)

javascript

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const file = await client.files.create({
  file: fs.createReadStream("screenshot.png"),
  purpose: "vision",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "مشکل UI را در این اسکرین‌شات توضیح بده." },
        { type: "input_image", file_id: file.id },
      ],
    },
  ],
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/files \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -F purpose="vision" \
  -F file="@screenshot.png"

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "مشکل UI را در این اسکرین‌شات توضیح بده."},
          {"type": "input_image", "file_id": "file_abc123"}
        ]
      }
    ]
  }'

ارائه URLهای تصویر

استفاده از API تکمیل گفتگو

محتوای یک تصویر را با استفاده از URL آن با نقطه پایانی تکمیل گفتگو تجزیه و تحلیل کنید:

python

# مثال پایتون با استفاده از تکمیل گفتگو با URL تصویر
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",  # نقطه پایانی API AvalAI
)

response = client.chat.completions.create(
    model="gpt-5.5",  # یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    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",
                        # اختیاری: تعیین سطح جزئیات
                        # "detail": "high" # یا "low" یا "auto" (پیش‌فرض)
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

javascript

// مثال جاوااسکریپت با استفاده از تکمیل گفتگو با URL تصویر
import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY, // اطمینان حاصل کنید که AVALAI_API_KEY تنظیم شده است
  baseURL: "https://api.avalai.ir/v1", // از URL پایه AvalAI استفاده کنید
});

async function main() {
  const response = await client.chat.completions.create({
    model: "gpt-5.5", // یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    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",
              // اختیاری: تعیین سطح جزئیات
              // detail: "high" // یا "low" یا "auto" (پیش‌فرض)
            },
          },
        ],
      },
    ],
  });

  console.log(response.choices[0].message.content);
}
main();

bash

# مثال cURL با استفاده از تکمیل گفتگو با URL تصویر
curl https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-5.5",
  "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"
          }
        }
      ]
    }
  ]
}'

go

// مثال Go با استفاده از تکمیل گفتگو با URL تصویر
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("AVALAI_API_KEY")),
		option.WithBaseURL("https://api.avalai.ir/v1"),
	)

	imageURL := "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

	resp, err := client.Chat.Completions.New(
		context.Background(),
		openai.ChatCompletionNewParams{
			Model: openai.F("gpt-5.5"),
			Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
				openai.UserMessage(
					openai.F([]openai.ChatCompletionContentPartUnionParam{
						openai.TextPart("در این تصویر چه چیزی وجود دارد؟"),
						openai.ImagePart(imageURL),
					}),
				),
			}),
		},
	)

	if err != nil {
		fmt.Printf("خطا در ایجاد تکمیل: %v\n", err)
		return
	}

	fmt.Println(resp.Choices[0].Message.Content)
}

php

<?php
// مثال PHP با استفاده از تکمیل گفتگو با URL تصویر
require 'vendor/autoload.php';

$apiKey = getenv('AVALAI_API_KEY');
$client = OpenAI::client($apiKey, [
  'base_url' => 'https://api.avalai.ir/v1',
]);

$response = $client->chat()->create([
  'model' => 'gpt-5.5',
  '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',
            // 'detail' => 'high' // اختیاری: تعیین سطح جزئیات
          ]
        ]
      ]
    ]
  ]
]);

echo $response->choices[0]->message->content;
?>

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

PythonJavaScriptBash

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "Describe this image." },
        { type: "input_image", image_url: "https://example.com/image.png" },
      ],
    },
  ],
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Describe this image."
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.png"
          }
        ]
      }
    ]
  }'

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

استفاده از API پاسخ‌ها

محتوای یک تصویر را با استفاده از URL آن با نقطه پایانی پاسخ‌ها تجزیه و تحلیل کنید:

python

# مثال پایتون با استفاده از AvalAI با URL تصویر
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",  # از URL پایه AvalAI استفاده کنید
)

response = client.responses.create(
    model="gpt-5.5",  # یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "در این تصویر چه چیزی وجود دارد؟"},
                {
                    "type": "input_image",
                    "image_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",
                    # اختیاری: تعیین سطح جزئیات
                    # "detail": "high" # یا "low" یا "auto" (پیش‌فرض)
                },
            ],
        }
    ],
)

# دسترسی به متن تولید شده (ممکن است بر اساس نسخه SDK متفاوت باشد)
if hasattr(response, "output_text"):
    print(response.output_text)

else:  # تجزیه دستی اگر output_text در دسترس نباشد
    text_output = ""
    if response.output and isinstance(response.output, list):
        for item in response.output:
            if (
                item.type == "message"
                and item.content
                and isinstance(item.content, list)
            ):
                for content_part in item.content:
                    if content_part.type == "output_text":
                        text_output += content_part.text + "\n"
    print(text_output.strip())

javascript

// مثال جاوااسکریپت با استفاده از AvalAI با URL تصویر
import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY, // اطمینان حاصل کنید که AVALAI_API_KEY تنظیم شده است
  baseURL: "https://api.avalai.ir/v1", // از URL پایه AvalAI استفاده کنید
});

async function main() {
  const response = await client.responses.create({
    model: "gpt-5.5", // یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    input: [
      {
        role: "user",
        content: [
          { type: "input_text", text: "در این تصویر چه چیزی وجود دارد؟" },
          {
            type: "input_image",
            image_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",
            // اختیاری: تعیین سطح جزئیات
            // detail: "high" // یا "low" یا "auto" (پیش‌فرض)
          },
        ],
      },
    ],
  });

  // دسترسی به متن تولید شده (ممکن است بر اساس نسخه SDK متفاوت باشد)
  if (response.output_text) {
    console.log(response.output_text);
  } else {
    // تجزیه دستی اگر output_text در دسترس نباشد
    let textOutput = "";
    if (response.output && Array.isArray(response.output)) {
      response.output.forEach((item) => {
        if (
          item.type === "message" &&
          item.content &&
          Array.isArray(item.content)
        ) {
          item.content.forEach((contentPart) => {
            if (contentPart.type === "output_text") {
              textOutput += contentPart.text + "\n";
            }
          });
        }
      });
    }
    console.log(textOutput.trim());
  }
}
main();

bash

# مثال cURL با استفاده از AvalAI با URL تصویر
curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-5.5",
  "input": [
  {
    "role": "user",
    "content": [
    {"type": "input_text", "text": "در این تصویر چه چیزی وجود دارد؟"},
    {
      "type": "input_image",
      "image_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"
    }
    ]
  }
  ]
}'

go

// مثال Go با استفاده از AvalAI با URL تصویر
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
)

func main() {
	// ایجاد کلاینت با استفاده از URL پایه AvalAI
	config := openai.DefaultConfig(os.Getenv("AVALAI_API_KEY"))
	config.BaseURL = "https://api.avalai.ir/v1"
	client := openai.NewClientWithConfig(config)

	// ایجاد درخواست با تصویر
	imageURL := "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

	resp, err := client.CreateResponse(
		context.Background(),
		openai.ResponseRequest{
			Model: "gpt-5.5",
			Input: []openai.ResponseMessage{
				{
					Role: "user",
					Content: []openai.ResponseContent{
						{
							Type: "input_text",
							Text: "در این تصویر چه چیزی وجود دارد؟",
						},
						{
							Type: "input_image",
							ImageURL: &openai.ImageURL{
								URL: imageURL,
								// Detail: "high", // اختیاری: تعیین سطح جزئیات
							},
						},
					},
				},
			},
		},
	)

	if err != nil {
		fmt.Printf("خطا در ایجاد پاسخ: %v\n", err)
		return
	}

	// استخراج متن از پاسخ
	var textOutput string
	for _, item := range resp.Output {
		if item.Type == "message" {
			for _, contentPart := range item.Content {
				if contentPart.Type == "output_text" {
					textOutput += contentPart.Text + "\n"
				}
			}
		}
	}

	fmt.Println(textOutput)
}

php

// مثال PHP با استفاده از AvalAI با URL تصویر
<?php
require 'vendor/autoload.php';

$apiKey = getenv('AVALAI_API_KEY');
$client = OpenAI::client($apiKey, [
'base_url' => 'https://api.avalai.ir/v1',
]);

$response = $client->responses()->create([
'model' => 'gpt-5.5',
'input' => [
[
'role' => 'user',
'content' => [
[
'type' => 'input_text',
'text' => 'در این تصویر چه چیزی وجود دارد؟'
],
[
'type' => 'input_image',
'image_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',
// 'detail' => 'high' // اختیاری: تعیین سطح جزئیات
]
]
]
]
]);

// استخراج متن از پاسخ
$textOutput = '';
if (isset($response->output_text)) {
  $textOutput = $response->output_text;
} else {
  // تجزیه دستی اگر output_text در دسترس نباشد
  foreach ($response->output as $item) {
    if ($item->type === 'message' && isset($item->content)) {
      foreach ($item->content as $contentPart) {
        if ($contentPart->type === 'output_text') {
          $textOutput .= $contentPart->text . "\n";
        }
      }
    }
  }
}

echo trim($textOutput);
?>

ارائه تصاویر کدگذاری شده Base64

استفاده از API تکمیل گفتگو

محتوای یک تصویر محلی را با کدگذاری آن در Base64 با نقطه پایانی تکمیل گفتگو تجزیه و تحلیل کنید:

PythonJavaScript

python

# مثال پایتون با استفاده از تکمیل گفتگو با تصویر Base64
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",  # از URL پایه AvalAI استفاده کنید
)


# تابع برای کدگذاری تصویر
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")


# مسیر تصویر شما
image_path = "path/to/your/image.jpg"  # این مسیر را به‌روز کنید

# دریافت رشته Base64
base64_image = encode_image(image_path)

response = client.chat.completions.create(
    model="gpt-5.5",  # یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "در این تصویر چه چیزی وجود دارد؟"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{base64_image}",  # در صورت نیاز نوع mime را تنظیم کنید
                        # اختیاری: تعیین سطح جزئیات
                        # "detail": "high"
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

javascript

// مثال جاوااسکریپت با استفاده از تکمیل گفتگو با تصویر Base64
import fs from "fs";
import path from "path"; // توصیه می‌شود برای مدیریت مسیرها
import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY, // اطمینان حاصل کنید که AVALAI_API_KEY تنظیم شده است
  baseURL: "https://api.avalai.ir/v1", // از URL پایه AvalAI استفاده کنید
});

async function main() {
  const imagePath = "path/to/your/image.jpg"; // این مسیر را به‌روز کنید
  const base64Image = fs.readFileSync(imagePath, "base64");
  const mimeType = "image/jpeg"; // در صورت استفاده از PNG، GIF و غیره تنظیم کنید.

  const response = await client.chat.completions.create({
    model: "gpt-5.5", // یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "در این تصویر چه چیزی وجود دارد؟" },
          {
            type: "image_url",
            image_url: {
              url: `data:${mimeType};base64,${base64Image}`,
              // اختیاری: تعیین سطح جزئیات
              // detail: "high"
            },
          },
        ],
      },
    ],
  });

  console.log(response.choices[0].message.content);
}
main();

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

PythonJavaScriptBash

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "Describe this image." },
        { type: "input_image", image_url: "https://example.com/image.png" },
      ],
    },
  ],
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Describe this image."
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.png"
          }
        ]
      }
    ]
  }'

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

استفاده از API پاسخ‌ها

محتوای یک تصویر محلی را با کدگذاری آن در Base64 با نقطه پایانی پاسخ‌ها تجزیه و تحلیل کنید:

PythonJavaScript

python

# مثال پایتون با استفاده از AvalAI با تصویر Base64
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",  # آدرس پایه
)


# تابع برای کدگذاری تصویر
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")


# مسیر تصویر شما
image_path = "path/to/your/image.jpg"  # این مسیر را به‌روز کنید

# دریافت رشته Base64
base64_image = encode_image(image_path)

response = client.responses.create(
    model="gpt-5.5",  # یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "در این تصویر چه چیزی وجود دارد؟"},
                {
                    "type": "input_image",
                    "image_url": f"data:image/jpeg;base64,{base64_image}",  # در صورت نیاز نوع mime را تنظیم کنید (مثلا image/png)
                    # اختیاری: تعیین سطح جزئیات
                    # "detail": "high"
                },
            ],
        }
    ],
)

# دسترسی به متن تولید شده (ممکن است بر اساس نسخه SDK متفاوت باشد)
if hasattr(response, "output_text"):
    print(response.output_text)
else:
    # منطق تجزیه دستی...
    pass

javascript

// مثال جاوااسکریپت با استفاده از AvalAI با تصویر Base64
import fs from "fs";
import path from "path"; // توصیه می‌شود برای مدیریت مسیرها
import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY, // اطمینان حاصل کنید که AVALAI_API_KEY تنظیم شده است
  baseURL: "https://api.avalai.ir/v1", // از URL پایه AvalAI استفاده کنید
});

async function main() {
  const imagePath = "path/to/your/image.jpg"; // این مسیر را به‌روز کنید
  const base64Image = fs.readFileSync(imagePath, "base64");
  const mimeType = "image/jpeg"; // در صورت استفاده از PNG، GIF و غیره تنظیم کنید.

  const response = await client.responses.create({
    model: "gpt-5.5", // یا مدل دیگری با قابلیت بینایی از طریق AvalAI
    input: [
      {
        role: "user",
        content: [
          { type: "input_text", text: "در این تصویر چه چیزی وجود دارد؟" },
          {
            type: "input_image",
            image_url: `data:${mimeType};base64,${base64Image}`,
            // اختیاری: تعیین سطح جزئیات
            // detail: "high"
          },
        ],
      },
    ],
  });

  // دسترسی به متن تولید شده (ممکن است بر اساس نسخه SDK متفاوت باشد)
  if (response.output_text) {
    console.log(response.output_text);
  } else {
    // منطق تجزیه دستی...
  }
}
main();

الزامات ورودی تصویر

تصاویر ورودی باید الزامات زیر را برآورده کنند:

انواع فایل: PNG (.png)، JPEG (.jpeg, .jpg)، WEBP (.webp)، GIF غیر متحرک (.gif)
اندازه inline در AvalAI: برای هر تصویر inline حداکثر 20 مگابایت است، مگر اینکه route ارائه‌دهنده محدودیت متفاوتی داشته باشد. برای assetهای تکراری یا بزرگ‌تر، file_id یا URL میزبانی‌شده را ترجیح دهید.
محدودیت مرجع routeهای OpenAI: مستندات مرجع vision در OpenAI تا 512 مگابایت payload کلی و تا 1500 ورودی تصویر در هر درخواست را توضیح می‌دهد، اما routing در AvalAI/ارائه‌دهنده می‌تواند محدودیت‌های سخت‌گیرانه‌تر حساب، endpoint یا gateway داشته باشد. تا وقتی route خود را تست نکرده‌اید، راهنمای 20 مگابایت inline را پیش‌فرض امن‌تر بدانید.
وضوح و detail: ارائه‌دهنده‌ها ممکن است تصویر را پیش از tokenization تغییر اندازه دهند. برای درک سریع از low، برای جزئیات بیشتر از high، برای screenshotهای متراکم یا وظایف فضایی در مدل‌های سازگار از original و فقط وقتی تغییر هزینه/وفاداری قابل قبول است از auto استفاده کنید.
محدودیت‌های محتوا: بدون واترمارک، لوگو یا محتوای NSFW. تصویر باید برای درک انسان به اندازه کافی واضح باشد؛ برای متن‌های کوچک، به‌جای ارسال screenshot شلوغ با وضوح کامل، متن را crop یا بزرگ کنید.

تعیین سطح جزئیات تصویر

از پارامتر detail در شی input_image برای کنترل جزئیات پردازش استفاده کنید:

"detail": "low": نمایی با وضوح کمتر پردازش می‌کند. در رفتار مرجع OpenAI این حالت نمایی در سبک 512px است و برای دسته‌بندی سریع، caption یا درک کلی صحنه مناسب است.
"detail": "high": درک تصویری با وفاداری بالاتر می‌دهد. وقتی متن، layout، جزئیات UI، نمودار یا اشیای کوچک مهم هستند استفاده کنید.
"detail": "original": در مدل‌ها/routeهای پشتیبانی‌شده، از جمله خانواده‌های جدید OpenAI gpt-5.4/gpt-5.5، جزئیات فضایی بیشتری را نگه می‌دارد. برای screenshotهای متراکم، localization و تحلیل شبیه computer-use مناسب است.
"detail": "auto": انتخاب را به مدل/ارائه‌دهنده می‌سپارد. در OpenAI gpt-5.5، مقدار auto و حذف کامل detail مانند original رفتار می‌کنند؛ در برخی خانواده‌های قدیمی‌تر ممکن است به رفتار high نزدیک‌تر باشد. اگر هزینه یا وفاداری باید قابل پیش‌بینی باشد، detail را صریح تنظیم کنید.

برای routeهای OpenAI، رفتار مرجع جدید چنین است:

سطح detail	اثر عملی
`low`	کم‌هزینه‌ترین گزینه؛ از نمای کاهش‌یافته در سبک 512px برای درک سریع صحنه استفاده می‌کند.
`high`	حالت استاندارد با وفاداری بالا؛ وقتی متن، UI، نمودار یا اشیای کوچک مهم هستند پیش‌فرض خوبی است.
`original`	در مدل‌های سازگار بیشترین جزئیات فضایی را حفظ می‌کند؛ برای screenshotهای متراکم، localization و تحلیل شبیه computer-use بهتر است.
`auto`	انتخاب را به مدل/ارائه‌دهنده می‌سپارد؛ در `gpt-5.5` مثل `original` رفتار می‌کند.

json

{
  "type": "input_image",
  "image_url": "...",
  "detail": "high"
}

اندازه‌بندی مدل و tokenization

OpenAI دو رفتار اصلی برای اندازه‌بندی تصویر توضیح می‌دهد: routeهای جدیدتر سبک GPT-5.5/GPT-5.4 می‌توانند از پردازش patch-based با patchهای 32px و بودجه patch مختص مدل استفاده کنند، در حالی که routeهای سبک GPT-4o/GPT-4.1/o-series برای تحلیل high-detail از حسابداری tile-based با tileهای 512px استفاده می‌کنند. AvalAI ممکن است درخواست‌های vision را از طریق OpenAI، Gemini، Anthropic یا ارائه‌دهندگان دیگر route کند؛ بنابراین محاسبات توکن OpenAI را کورکورانه برای همه ارائه‌دهندگان کپی نکنید. detail را کنترل قابل‌حمل هزینه/وفاداری بدانید و سپس مصرف واقعی را در metadata پاسخ، جزئیات مدل‌ها و قیمت‌گذاری بررسی کنید.

ورودی‌های چند تصویری

می‌توانید چندین تصویر را در یک نوبت کاربر بفرستید. در Chat Completions چند part از نوع image_url را داخل messages[].content بگذارید؛ در Responses چند part از نوع input_image را داخل input[].content قرار دهید. هر تصویر هزینه توکن و latency را افزایش می‌دهد، پس فقط نماهای لازم برای task را ارسال کنید.

استفاده از API تکمیل گفتگو

python

# مثال با چندین تصویر با استفاده از تکمیل گفتگو
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "در این تصاویر چه چیزهایی وجود دارد؟ آیا تفاوتی وجود دارد؟",
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "URL_TO_IMAGE_1", "detail": "low"},
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "URL_TO_IMAGE_2", "detail": "low"},
                },
            ],
        }
    ],
)
print(response.choices[0].message.content)

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "در این تصاویر چه چیزهایی وجود دارد؟ آیا تفاوتی وجود دارد؟",
                },
                {"type": "input_image", "image_url": "URL_TO_IMAGE_1", "detail": "low"},
                {"type": "input_image", "image_url": "URL_TO_IMAGE_2", "detail": "low"},
            ],
        }
    ],
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

استفاده از API پاسخ‌ها

python

# مثال با چندین تصویر با استفاده از پاسخ‌ها
response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "در این تصاویر چه چیزهایی وجود دارد؟ آیا تفاوتی وجود دارد؟",
                },
                {"type": "input_image", "image_url": "URL_TO_IMAGE_1", "detail": "low"},
                {"type": "input_image", "image_url": "URL_TO_IMAGE_2", "detail": "low"},
            ],
        }
    ],
)
# print(response.output_text)

محدودیت‌ها

هنگام استفاده از قابلیت‌های بینایی از محدودیت‌های زیر آگاه باشید:

تصویربرداری پزشکی: برای تفسیر تصاویر پزشکی تخصصی (CT، MRI) یا تشخیص پزشکی مناسب نیست.
الفبای غیر لاتین: عملکرد ممکن است در تصاویر حاوی متن به خط‌هایی مانند ژاپنی، کره‌ای و غیره کاهش یابد.
متن کوچک: متن را برای خوانایی بهتر بزرگ کنید، اما از برش زمینه حیاتی خودداری کنید.
سطح جزئیات: برای درک سریع و کم‌هزینه از detail: "low" استفاده کنید؛ وقتی متن کوچک، چیدمان فضایی یا وفاداری اسکرین‌شات مهم است، در مدل‌های پشتیبانی‌شده از high، auto یا original استفاده کنید.
چرخش: متن و تصاویر چرخانده/وارونه ممکن است به اشتباه تفسیر شوند.
عناصر بصری: درک نمودارهای پیچیده یا تغییرات سبک (مانند خطوط تیره در مقابل خطوط نقطه‌چین) دشوار است.
استدلال فضایی: دقت محدود برای وظایفی که نیاز به محلی‌سازی فضایی دقیق دارند (مانند موقعیت‌های شطرنج).
دقت: ممکن است گاهی اوقات توضیحات یا زیرنویس‌های نادرست تولید کند.
شکل تصویر: با تصاویر پانوراما و چشم ماهی مشکل دارد.
فراداده: نام فایل‌های اصلی یا فراداده EXIF را پردازش نمی‌کند.
تغییر اندازه: تصاویر ممکن است بر اساس سطح جزئیات انتخاب‌شده قبل از تحلیل تغییر اندازه داده شوند و به طور بالقوه اطلاعات ابعاد اصلی را از دست بدهند.
شمارش: شمارش اشیا ممکن است تقریبی باشد.
کپچاها: به دلایل ایمنی مسدود شده است.

قابلیت‌های تصویری مختص Gemini

مدل‌های فعلی Gemini گوگل، از جمله gemini-3.5-flash، gemini-3.1-pro-preview، gemini-3.1-flash-lite، gemini-2.5-pro و gemini-2.5-flash، چندین قابلیت پیشرفته درک تصویر را از طریق AvalAI ارائه می‌دهند:

تشخیص اشیا با کادرهای محدودکننده (Bounding Box)

مدل‌های Gemini می‌توانند اشیا را در تصاویر تشخیص دهند و مختصات کادر محدودکننده آنها را ارائه دهند. مختصات نسبت به ابعاد تصویر، مقیاس‌بندی شده به [0, 1000] برگردانده می‌شوند. شما باید این مختصات را بر اساس اندازه اصلی تصویر خود مقیاس‌بندی معکوس کنید.

برای دریافت کادرهای محدودکننده، دستورالعمل واضحی در پرامپت خود قرار دهید:

استفاده از API تکمیل گفتگو:

python

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "تمام اشیا برجسته در این تصویر را تشخیص دهید و کادرهای محدودکننده را در قالب [ymin, xmin, ymax, xmax] نرمال‌سازی شده به 0-1000 ارائه دهید.",
                },
                {
                    "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"
                    },
                },
            ],
        }
    ],
)
print(response.choices[0].message.content)

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-3.1-pro-preview` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

استفاده از API پاسخ‌ها:

python

response = client.responses.create(
    model="gemini-3.1-pro-preview",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "تمام موارد برجسته در این تصویر را تشخیص بده. کادرهای محدودکننده را در قالب [ymin, xmin, ymax, xmax] نرمال‌سازی شده به 0-1000 برگردان.",
                },
                {"type": "input_image", "image_url": "data:image/jpeg;base64,..."},
            ],
        }
    ],
)

برای تبدیل مختصات نرمال‌سازی شده به مختصات پیکسل:

هر مختصات خروجی را بر 1000 تقسیم کنید
مختصات x را در عرض اصلی تصویر ضرب کنید
مختصات y را در ارتفاع اصلی تصویر ضرب کنید

قطعه‌بندی تصویر (Image Segmentation)

از مدل‌های Gemini 2.5 به بعد و در خانواده Gemini 3.1، Gemini همچنین می‌تواند اشیا را قطعه‌بندی کرده و ماسک‌های کانتور آنها را ارائه دهد. ماسک‌های قطعه‌بندی را با دستورالعمل واضح درخواست کنید:

استفاده از API تکمیل گفتگو:

python

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "ماسک‌های قطعه‌بندی را برای اشیا چوبی ارائه کن. یک لیست JSON خروجی بده که هر ورودی شامل کادر محدودکننده، ماسک و برچسب باشد.",
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "data:image/jpeg;base64,..."},
                },
            ],
        }
    ],
)

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-3.1-pro-preview` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

استفاده از API پاسخ‌ها:

python

response = client.responses.create(
    model="gemini-3.1-pro-preview",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "ماسک‌های قطعه‌بندی را برای اشیا چوبی ارائه کن. یک لیست JSON خروجی بده که هر ورودی شامل کادر محدودکننده، ماسک و برچسب باشد.",
                },
                {"type": "input_image", "image_url": "data:image/jpeg;base64,..."},
            ],
        }
    ],
)

نکات مهم برای مدل‌های Gemini

فقط Base64: هنگام استفاده از مدل‌های Gemini از طریق AvalAI، تصاویر باید به صورت رشته‌های کدگذاری شده base64 ارائه شوند. ورودی‌های تصویر مبتنی بر URL برای مدل‌های Gemini پشتیبانی نمی‌شوند.
محدودیت‌های فایل: Gemini 3.1، Gemini 2.5 Pro، 2.0 Flash، 1.5 Pro و 1.5 Flash حداکثر از 3,600 فایل تصویری در هر درخواست پشتیبانی می‌کنند.
فرمت‌های پشتیبانی شده: فرمت‌های PNG، JPEG، WEBP، HEIC و HEIF پشتیبانی می‌شوند.

محاسبه توکن برای مدل‌های Gemini

محاسبه توکن بر اساس مدل Gemini متفاوت است:

Gemini 3.1 / 2.5 Flash: 258 توکن اگر هر دو بعد ≤ 384 پیکسل باشند. تصاویر بزرگتر به کاشی‌های 768x768 پیکسلی تقسیم می‌شوند، که هر کدام 258 توکن هزینه دارند.

Gemini Robotics-ER: بینایی برای رباتیک فیزیکی

مدل gemini-robotics-er-1.5-preview اولین مدل بینایی-زبان گوگل است که به طور خاص برای کاربردهای رباتیک طراحی شده است. این مدل در درک صحنه‌های فیزیکی، روابط فضایی و تولید دستورات قابل اجرا برای ربات‌ها از ورودی بصری عالی است.

قابلیت‌های کلیدی

تشخیص اشیاء با مختصات: نقاط دقیق 2D [y, x] و کادرهای محدودکننده [ymin, xmin, ymax, xmax] را در مختصات نرمال شده (0-1000) برمی‌گرداند
استدلال فضایی: روابط اشیاء و زمینه صحنه را درک می‌کند
برنامه‌ریزی مسیر: مسیرهای نقطه عبور را برای حرکت ربات تولید می‌کند
هماهنگی وظایف: دستورات زبان طبیعی را به زیروظایف قابل اجرا تقسیم می‌کند

مثال سریع

python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("AVALAI_API_KEY"),
    base_url="https://api.avalai.ir/v1",
)

response = client.chat.completions.create(
    model="gemini-robotics-er-1.5-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "به فنجان قرمز اشاره کن"},
                {
                    "type": "image_url",
                    "image_url": {"url": "data:image/jpeg;base64,..."},
                },
            ],
        }
    ],
)

# پاسخ شامل مختصات نرمال شده است:
# "فنجان قرمز در نقطه [450, 620] قرار دارد"

نسخه معادل Responses API مدل این نسخه روی `gpt-5.5` تنظیم شده، چون `gemini-robotics-er-1.5-preview` ممکن است در داده‌های فعلی AvalAI برای `/v1/responses` فعال نباشد.

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe this image."},
                {"type": "input_image", "image_url": "https://example.com/image.png"},
            ],
        }
    ],
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

چه زمانی از Robotics-ER استفاده کنیم

کنترل ربات فیزیکی که نیازمند درک دقیق فضایی است
محلی‌سازی اشیاء با خروجی مختصات نرمال شده
برنامه‌ریزی وظایف چند مرحله‌ای برای دستکاری‌کننده‌های رباتیک
درک صحنه برای ناوبری و نظارت ایمنی

برای راهنمای جامع استفاده از این مدل شامل برنامه‌ریزی مسیر، استدلال فضایی و کاربردهای پیشرفته رباتیک، آموزش کامل را ببینید: هوش مصنوعی در رباتیک با Gemini Robotics-ER.

محاسبه هزینه‌ها

ورودی‌های تصویر مثل متن با توکن حساب می‌شوند و هزینه به خانواده مدل، ابعاد تصویر، تعداد تصاویر و مقدار detail بستگی دارد.

low معمولا با ارسال نمای کوچک‌تر، هزینه و latency را کاهش می‌دهد.
high و original اطلاعات بصری بیشتری حفظ می‌کنند، اما می‌توانند توکن ورودی بیشتری مصرف کنند.
چند تصویر با هم جمع می‌شوند؛ زاویه‌ها، thumbnailها یا screenshotهای تکراری را که روی پاسخ اثر ندارند حذف کنید.
ورودی PDF می‌تواند از متن ساده پرهزینه‌تر باشد، چون routeهای بینایی ممکن است هم متن استخراج‌شده و هم تصویر صفحه‌ها را پردازش کنند.
Routing ارائه‌دهنده مهم است: OpenAI، Gemini، Anthropic و سایر ارائه‌دهندگان ممکن است تصویر را متفاوت tokenize کنند.
حسابداری patch در برابر tile بر اساس خانواده مدل متفاوت است. OpenAI برای tokenization تصویر در مدل‌های جدیدتر سبک GPT-5 از بودجه patchهای 32px و برای تحلیل high-detail در خانواده‌های سبک GPT-4o/GPT-4.1/o-series از حسابداری tileهای 512px صحبت می‌کند؛ کاربران AvalAI همچنان باید به usage و قیمت route انتخابی تکیه کنند.

پیش از rollout production، تصویرهای نماینده را تست کنید، مصرف توکن ورودی را log بگیرید و نتیجه را با جزئیات مدل‌ها، قیمت‌گذاری و محدودیت‌های نرخ مقایسه کنید.

بینایی (ورودی تصویر) ​

فهرست مطالب ​

نقاط پایانی API ​

مدل‌های پیشنهادی بینایی ​

روش‌های ورودی تصویر ​

چک‌لیست طراحی وظیفه بینایی ​

ارائه شناسه فایل تصویر ​

ارائه URLهای تصویر ​

استفاده از API تکمیل گفتگو ​

استفاده از API پاسخ‌ها ​

ارائه تصاویر کدگذاری شده Base64 ​

استفاده از API تکمیل گفتگو ​

استفاده از API پاسخ‌ها ​

الزامات ورودی تصویر ​

تعیین سطح جزئیات تصویر ​

اندازه‌بندی مدل و tokenization ​

ورودی‌های چند تصویری ​

استفاده از API تکمیل گفتگو ​

استفاده از API پاسخ‌ها ​

محدودیت‌ها ​

قابلیت‌های تصویری مختص Gemini ​

تشخیص اشیا با کادرهای محدودکننده (Bounding Box) ​

قطعه‌بندی تصویر (Image Segmentation) ​

نکات مهم برای مدل‌های Gemini ​

محاسبه توکن برای مدل‌های Gemini ​

Gemini Robotics-ER: بینایی برای رباتیک فیزیکی ​

قابلیت‌های کلیدی ​

مثال سریع ​

چه زمانی از Robotics-ER استفاده کنیم ​

محاسبه هزینه‌ها ​

بینایی (ورودی تصویر)

فهرست مطالب

نقاط پایانی API

مدل‌های پیشنهادی بینایی

روش‌های ورودی تصویر

چک‌لیست طراحی وظیفه بینایی

ارائه شناسه فایل تصویر

ارائه URLهای تصویر

استفاده از API تکمیل گفتگو

استفاده از API پاسخ‌ها

ارائه تصاویر کدگذاری شده Base64

استفاده از API تکمیل گفتگو

استفاده از API پاسخ‌ها

الزامات ورودی تصویر

تعیین سطح جزئیات تصویر

اندازه‌بندی مدل و tokenization

ورودی‌های چند تصویری

استفاده از API تکمیل گفتگو

استفاده از API پاسخ‌ها

محدودیت‌ها

قابلیت‌های تصویری مختص Gemini

تشخیص اشیا با کادرهای محدودکننده (Bounding Box)

قطعه‌بندی تصویر (Image Segmentation)

نکات مهم برای مدل‌های Gemini

محاسبه توکن برای مدل‌های Gemini

Gemini Robotics-ER: بینایی برای رباتیک فیزیکی

قابلیت‌های کلیدی

مثال سریع

چه زمانی از Robotics-ER استفاده کنیم

محاسبه هزینه‌ها