ورودی تصویر — Image Inputs

آشا ارسال تصویر به مدل‌های چندوجهی را از طریق endpoint /v1/chat/completions و با پارامتر messages چندبخشی پشتیبانی می‌کند. فیلد image_url می‌تواند یک URL یا تصویری با کدگذاری base64 باشد. تصاویر متعدد را می‌توان در آیتم‌های جداگانهٔ آرایهٔ content فرستاد.

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

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

استفاده از URL تصویر

برای تصاویر عمومی، می‌توانید URL را مستقیم بفرستید بدون اینکه لازم باشد تصویر را دانلود و کد کنید:

import os

import requests

url = "https://app.asha-ai.ir/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What is in this image?",
            },
            {
                "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-3-flash-preview",
    "messages": messages,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch(
  "https://app.asha-ai.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "~google/gemini-3-flash-preview",
      messages: [
        {
          role: "user",
          content: [
            { type: "text", text: "What is in this image?" },
            {
              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",
              },
            },
          ],
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);

curl https://app.asha-ai.ir/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -d '{
    "model": "~google/gemini-3-flash-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is in this image?" },
          { "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" } }
        ]
      }
    ]
  }'

استفاده از تصاویر با کدگذاری Base64

برای تصاویر ذخیره‌شده به‌صورت محلی، می‌توانید آن‌ها را با کدگذاری base64 بفرستید:

import base64
import os

import requests

def encode_image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

url = "https://app.asha-ai.ir/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

# Read and encode the image
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": "What is in this image?",
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": data_url,
                },
            },
        ],
    }
]

payload = {
    "model": "~google/gemini-3-flash-preview",
    "messages": messages,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

import fs from "fs/promises";

async function encodeImageToBase64(imagePath: string): Promise<string> {
  const imageBuffer = await fs.readFile(imagePath);
  const base64Image = imageBuffer.toString("base64");
  return `data:image/jpeg;base64,${base64Image}`;
}

// Read and encode the image
const imagePath = "path/to/your/image.jpg";
const base64Image = await encodeImageToBase64(imagePath);

const response = await fetch(
  "https://app.asha-ai.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "~google/gemini-3-flash-preview",
      messages: [
        {
          role: "user",
          content: [
            { type: "text", text: "What is in this image?" },
            {
              type: "image_url",
              image_url: {
                url: base64Image,
              },
            },
          ],
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);

# Base64-encode your image file
IMAGE_BASE64=$(base64 < image.jpg | tr -d 'n')
DATA_URL="data:image/jpeg;base64,$IMAGE_BASE64"

curl https://app.asha-ai.ir/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -d '{
    "model": "~google/gemini-3-flash-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is in this image?" },
          { "type": "image_url", "image_url": { "url": "'"$DATA_URL"'" } }
        ]
      }
    ]
  }'

فرمت‌های پشتیبانی‌شده

نوع محتوای تصاویری که درخواست می‌تواند بپذیرد:

image/png
image/jpeg
image/webp
image/gif

سؤالات متداول

آیا می‌توانم چند تصویر را در یک درخواست بفرستم؟

بله؛ هر تصویر باید به‌صورت یک آیتم جداگانه در آرایهٔ content قرار گیرد. تعداد محدود ممکن به ارائه‌دهنده و مدل بستگی دارد.

URL بهتر است یا base64؟

برای تصاویر عمومی URL کارآمدتر است. برای فایل‌های محلی یا تصاویر خصوصی باید از base64 استفاده کنید.

کدام فرمت‌های تصویر پشتیبانی می‌شوند؟

فرمت‌های image/png، image/jpeg، image/webp و image/gif.

چرا باید متن prompt را اول بفرستم؟

به دلیل نحوهٔ تجزیهٔ محتوا. اگر ناگزیر تصاویر باید اول باشند، بهتر است آن‌ها را در system prompt قرار دهید.

چند تصویر می‌توانم در هر درخواست بفرستم؟

حد مجاز بسته به ارائه‌دهنده و مدل متفاوت است؛ برای هر مدل به مستندات یا صفحهٔ مدل‌ها مراجعه کنید.