مقدمه

تولید تصویر با هوش مصنوعی طی چند سال گذشته از یک قابلیت جذاب به یکی از مهم‌ترین ابزارهای توسعه نرم‌افزار تبدیل شده است. امروزه بسیاری از محصولات دیجیتال برای تولید خودکار تصویر به مدل‌های هوش مصنوعی متکی هستند؛ از ساخت کاور مقاله و تصاویر شبکه‌های اجتماعی گرفته تا طراحی تصاویر محصولات فروشگاهی، بنرهای تبلیغاتی، رابط‌های کاربری، شخصیت‌های بازی و محتوای بازاریابی.

در گذشته برای استفاده از هر مدل تولید تصویر باید به API اختصاصی همان ارائه‌دهنده متصل می‌شدید. این موضوع باعث می‌شد هر سرویس ساختار درخواست، روش احراز هویت، پارامترها و مدل‌های مخصوص به خود را داشته باشد و نگهداری پروژه با اضافه شدن ارائه‌دهندگان جدید دشوارتر شود.

API درواره این فرایند را ساده کرده است. با یک API سازگار با استاندارد OpenAI می‌توانید به مجموعه‌ای از مدل‌های تولید تصویر دسترسی داشته باشید و بدون تغییر معماری برنامه، از مدل مناسب برای هر پروژه استفاده کنید.

تمام درخواست‌های تولید تصویر در درواره از طریق یک آدرس ثابت ارسال می‌شوند:

https://api.darvareh.ir/v1

در این مقاله یاد می‌گیرید چگونه:

• اولین تصویر خود را با API درواره تولید کنید.
• پارامترهای مختلف Image Generation را بشناسید.
• تصویر را به صورت URL یا Base64 دریافت کنید.
• با JavaScript و Python از API استفاده کنید.
• بهترین Promptها را برای تولید تصاویر باکیفیت بنویسید.
• از قابلیت تحلیل تصویر (Vision) در مدل‌های چندوجهی استفاده کنید.

API تولید تصویر چیست؟

Image Generation API سرویسی است که به برنامه شما اجازه می‌دهد تنها با ارسال یک توضیح متنی (Prompt)، تصویر جدید تولید کند.

برای مثال اگر درخواست زیر را ارسال کنید:

یک تصویر سینمایی از یک شهر آینده‌نگر با نورهای بنفش، معماری مدرن، کیفیت بسیار بالا و سبک فوتورئالیستی

مدل هوش مصنوعی بر اساس همین توضیح، تصویر جدیدی تولید می‌کند.

این قابلیت در ده‌ها سناریوی واقعی استفاده می‌شود؛ از جمله:

• تولید کاور مقاله
• ساخت تصاویر شبکه‌های اجتماعی
• تولید تصاویر محصولات فروشگاهی
• طراحی شخصیت
• تولید تصاویر تبلیغاتی
• طراحی اولیه رابط کاربری
• تولید تصاویر آموزشی
• تصویرسازی برای کتاب و مجله
• تولید تصاویر وب‌سایت
• ساخت محتوای خلاقانه

چرا از API درواره استفاده کنیم؟

یکی از چالش‌های رایج هنگام استفاده از مدل‌های هوش مصنوعی، تفاوت APIهای ارائه‌دهندگان مختلف است. هر ارائه‌دهنده ساختار مخصوص خود را دارد و با اضافه شدن مدل‌های جدید، نگهداری کد پیچیده‌تر می‌شود.

درواره این پیچیدگی را حذف می‌کند و یک API یکپارچه در اختیار توسعه‌دهندگان قرار می‌دهد.

مهم‌ترین مزایای استفاده از API درواره عبارت‌اند از:

• دسترسی به مدل‌های مختلف تولید تصویر از طریق یک API
• سازگاری با استاندارد OpenAI
• استفاده از یک Base URL ثابت
• احراز هویت ساده با API Key
• امکان استفاده در JavaScript، Python، PHP، Go، Java و سایر زبان‌ها
• مناسب برای وب‌سایت‌ها، اپلیکیشن‌های موبایل و سرویس‌های بک‌اند
• مستندات فارسی و نمونه‌کدهای آماده

پیش‌نیازها

برای استفاده از Image Generation API تنها به سه مورد نیاز دارید:

۱. ایجاد حساب کاربری در درواره

۲. دریافت API Key

۳. شارژ کیف پول حساب کاربری

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

https://api.darvareh.ir/v1

تمام درخواست‌ها باید هدر Authorization را داشته باشند:

Authorization: Bearer YOUR_DARVAREH_API_KEY

ساختار Image Generation API در درواره

در مستندات فعلی درواره، تولید تصویر از طریق Endpoint زیر انجام می‌شود:

POST /v1/images/generations

در ساده‌ترین حالت تنها کافی است نام مدل و Prompt را ارسال کنید.

نمونه درخواست:

{
  "model": "openai/gpt-image-1",
  "prompt": "A cinematic futuristic city at sunset"
}

در ادامه مقاله، تمام پارامترهای این Endpoint را به‌صورت کامل بررسی خواهیم کرد.

اولین درخواست تولید تصویر

در ساده‌ترین حالت، درخواست تولید تصویر به شکل زیر است:

curl https://api.darvareh.ir/v1/images/generations \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"openai/gpt-image-1",
    "prompt":"A premium workspace with futuristic AI devices"
}'

اگر درخواست با موفقیت انجام شود، پاسخ شامل تصویر تولیدشده خواهد بود. بسته به مقدار پارامتر response_format، تصویر ممکن است به‌صورت URL یا Base64 بازگردانده شود.

پارامترهای اصلی درخواست

Endpoint تولید تصویر در درواره از پارامترهای زیر پشتیبانی می‌کند.

در بخش‌های بعدی، هر یک از این پارامترها را به همراه مثال‌های عملی بررسی خواهیم کرد.

عالی. از این قسمت وارد بخش فنی مقاله می‌شویم و تمام مثال‌ها را مطابق مستندات فعلی درواره می‌نویسیم.

پارامترهای Image Generation API

علاوه بر model و prompt، می‌توانید با استفاده از چند پارامتر اختیاری، کیفیت، تعداد و نوع خروجی تصویر را کنترل کنید. البته توجه داشته باشید که همه مدل‌ها از تمام پارامترها پشتیبانی نمی‌کنند؛ بنابراین هنگام انتخاب مدل، مستندات همان مدل را نیز بررسی کنید.

در ادامه، هر پارامتر را به‌صورت جداگانه بررسی می‌کنیم.

انتخاب مدل (model)

پارامتر model مشخص می‌کند درخواست تولید تصویر توسط کدام مدل هوش مصنوعی پردازش شود.

نمونه:

{
  "model": "openai/gpt-image-1",
  "prompt": "A premium smartwatch on a white background"
}

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

درواره دسترسی به مدل‌های مختلف را از طریق یک API یکپارچه فراهم می‌کند؛ بنابراین معمولاً تنها کافی است مقدار model را تغییر دهید و سایر بخش‌های برنامه بدون تغییر باقی می‌مانند.

نوشتن Prompt مناسب

مهم‌ترین عامل در کیفیت خروجی، Prompt است.

مدل تنها بر اساس توضیحی که ارسال می‌کنید تصویر را تولید می‌کند؛ بنابراین هرچه Prompt دقیق‌تر باشد، نتیجه نیز بهتر خواهد بود.

مثال ضعیف:

یک لپ‌تاپ

مثال بهتر:

A premium ultra-thin silver laptop on a clean white desk, soft natural lighting, realistic photography, minimal style

نمونه مناسب برای تولید کاور مقاله:

A modern blog cover about artificial intelligence, dark navy background, subtle purple lighting, clean minimal design, futuristic technology, no text

نمونه مناسب برای تصویر محصول:

Professional studio product photography of wireless earbuds on a white background with soft shadows, highly detailed

نمونه مناسب برای شبکه‌های اجتماعی:

A clean modern illustration representing AI automation, vibrant colors, minimal composition, professional marketing style

چند توصیه برای نوشتن Prompt

Prompt بهتر معمولاً شامل این بخش‌هاست:

• موضوع اصلی
• سبک تصویر
• نوع نورپردازی
• رنگ غالب
• زاویه دوربین
• کیفیت تصویر
• فضای کلی
• مواردی که نباید در تصویر وجود داشته باشند

برای مثال:

Modern office, cinematic lighting, realistic photography, shallow depth of field, premium design, minimal composition, no text

تعداد تصاویر (n)

اگر مدل انتخابی از تولید چند تصویر پشتیبانی کند، می‌توانید با پارامتر n چند تصویر را در یک درخواست تولید کنید.

نمونه:

{
  "model": "openai/gpt-image-1",
  "prompt": "A futuristic city skyline",
  "n": 4
}

در این حالت مدل چهار تصویر مختلف تولید می‌کند.

اگر این پارامتر ارسال نشود، معمولاً یک تصویر تولید خواهد شد.

توجه داشته باشید که افزایش مقدار n باعث افزایش مصرف اعتبار نیز می‌شود.

انتخاب اندازه تصویر (size)

پارامتر size ابعاد خروجی تصویر را مشخص می‌کند.

نمونه:

{
  "model": "openai/gpt-image-1",
  "prompt": "Luxury living room interior",
  "size": "1024x1024"
}

بسته به مدل انتخابی، اندازه‌های مختلفی قابل استفاده هستند.

برخی از اندازه‌های رایج عبارت‌اند از:

قبل از استفاده از اندازه‌های خاص، بهتر است محدودیت‌های مدل انتخابی را بررسی کنید.

کیفیت تصویر (quality)

برخی مدل‌ها امکان انتخاب کیفیت خروجی را فراهم می‌کنند.

نمونه:

{
  "model": "openai/gpt-image-1",
  "prompt": "A luxury hotel lobby",
  "quality": "hd"
}

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

اگر کیفیت برای پروژه اهمیت زیادی ندارد، استفاده از مقدار standard می‌تواند زمان تولید و هزینه را کاهش دهد.

سبک تصویر (style)

برخی مدل‌ها از پارامتر style پشتیبانی می‌کنند.

این پارامتر نوع پردازش هنری تصویر را مشخص می‌کند.

نمونه:

{
  "model": "openai/gpt-image-1",
  "prompt": "A modern AI workspace",
  "style": "vivid"
}

مقادیر رایج عبارت‌اند از:

اگر قصد تولید تصاویر تبلیغاتی دارید، معمولاً vivid انتخاب مناسبی است.

برای تصاویر مستند یا واقعی، natural نتیجه طبیعی‌تری ایجاد می‌کند.

فرمت پاسخ (response_format)

درواره می‌تواند تصویر تولیدشده را به دو روش بازگرداند:

• URL
• Base64

نمونه:

{
  "model": "openai/gpt-image-1",
  "prompt": "A modern office",
  "response_format": "url"
}

یا

{
  "response_format": "b64_json"
}

انتخاب روش مناسب به معماری پروژه بستگی دارد.

دریافت تصویر به صورت URL

اگر مقدار response_format برابر url باشد، پاسخ API مشابه نمونه زیر خواهد بود:

{
  "created": 1748372400,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

در این حالت کافی است URL را در مرورگر یا تگ <img> استفاده کنید.

این روش برای بیشتر پروژه‌های وب مناسب‌تر است زیرا نیازی به Decode کردن Base64 وجود ندارد.

دریافت تصویر به صورت Base64

اگر مقدار response_format برابر b64_json باشد، پاسخ به شکل زیر خواهد بود:

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<BASE64>"
    }
  ]
}

در این حالت تصویر مستقیماً داخل پاسخ قرار می‌گیرد.

این روش برای موارد زیر بسیار مناسب است:

• ذخیره مستقیم در پایگاه داده
• ارسال به سرویس دیگر
• پردازش تصویر
• اپلیکیشن‌های موبایل
• محیط‌هایی که فایل موقت ندارند

ذخیره تصویر Base64 در Python

اگر پاسخ را به صورت Base64 دریافت کرده باشید، تبدیل آن به فایل بسیار ساده است.

import base64

image = result["data"][0]["b64_json"]

with open("output.png", "wb") as f:
    f.write(base64.b64decode(image))

در پایان، فایل output.png در پوشه پروژه ذخیره خواهد شد.

اولین نمونه کامل با cURL

در مثال زیر تقریباً تمام پارامترهای رایج را مشاهده می‌کنید.

curl https://api.darvareh.ir/v1/images/generations \
-H "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model":"openai/gpt-image-1",
  "prompt":"A futuristic AI command center with dark navy colors and subtle purple lighting",
  "size":"1536x1024",
  "quality":"hd",
  "style":"vivid",
  "response_format":"url"
}'

این درخواست یک تصویر افقی با کیفیت بالا تولید می‌کند که برای استفاده به‌عنوان کاور مقاله یا بنر وب‌سایت مناسب است.

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

استفاده از Image Generation API در JavaScript

اگر در حال توسعه یک وب‌سایت، اپلیکیشن Node.js یا Backend جاوااسکریپتی هستید، می‌توانید با استفاده از fetch تنها در چند خط کد تصویر تولید کنید.

نمونه زیر یک تصویر ایجاد کرده و آدرس آن را چاپ می‌کند.

const response = await fetch("https://api.darvareh.ir/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DARVAREH_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "openai/gpt-image-1",
    prompt: "A modern AI workspace with futuristic design",
    size: "1536x1024",
    quality: "hd",
    response_format: "url"
  })
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();

console.log(result.data[0].url);

اگر از متغیرهای محیطی استفاده می‌کنید، هرگز API Key را مستقیماً داخل کد قرار ندهید.

در پروژه‌های Node.js معمولاً از فایل .env استفاده می‌شود.

DARVAREH_API_KEY=xxxxxxxxxxxxxxxx

دریافت تصویر به صورت Base64 در JavaScript

اگر قصد دارید تصویر را مستقیماً ذخیره کنید یا به سرویس دیگری ارسال نمایید، استفاده از Base64 مناسب‌تر است.

const response = await fetch("https://api.darvareh.ir/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DARVAREH_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "openai/gpt-image-1",
    prompt: "A premium product photo",
    response_format: "b64_json"
  })
});

const result = await response.json();

const base64 = result.data[0].b64_json;

در این حالت می‌توانید Base64 را در فایل، پایگاه داده یا فضای ذخیره‌سازی ابری ذخیره کنید.

استفاده از Image Generation API در Python

کتابخانه requests ساده‌ترین روش برای ارتباط با API درواره است.

import requests
import os

response = requests.post(
    "https://api.darvareh.ir/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['DARVAREH_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "model": "openai/gpt-image-1",
        "prompt": "A cinematic AI server room",
        "size": "1536x1024",
        "quality": "hd",
        "response_format": "url"
    }
)

response.raise_for_status()

result = response.json()

print(result["data"][0]["url"])

ذخیره تصویر Base64 در Python

اگر پاسخ به صورت Base64 باشد، تنها کافی است آن را Decode کنید.

import base64

image = result["data"][0]["b64_json"]

with open("output.png", "wb") as file:
    file.write(base64.b64decode(image))

پس از اجرای برنامه، فایل تصویر در مسیر پروژه ذخیره خواهد شد.

مدیریت خطاها

مانند هر API دیگری، ممکن است درخواست تولید تصویر با خطا مواجه شود.

رایج‌ترین دلایل عبارت‌اند از:

• API Key نامعتبر
• اعتبار ناکافی کیف پول
• نام مدل اشتباه
• Prompt نامعتبر
• محدودیت نرخ درخواست (Rate Limit)
• خطای موقت سرویس

در JavaScript بهتر است همیشه وضعیت پاسخ بررسی شود.

if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
}

در Python نیز استفاده از raise_for_status() باعث می‌شود خطاهای HTTP به‌درستی مدیریت شوند.

response.raise_for_status()

در پروژه‌های Production بهتر است علاوه بر ثبت خطا، مکانیزمی برای Retry نیز در نظر بگیرید.

انتخاب اندازه مناسب برای هر کاربرد

یکی از اشتباهات رایج، استفاده از یک اندازه ثابت برای تمام تصاویر است.

بهتر است اندازه تصویر متناسب با کاربرد انتخاب شود.

استفاده از اندازه‌های بزرگ‌تر معمولاً هزینه و زمان تولید را نیز افزایش می‌دهد.

اگر کیفیت بسیار بالا نیاز ندارید، از اندازه‌های کوچک‌تر استفاده کنید.

بهترین روش‌های استفاده در محیط Production

اگر قصد دارید قابلیت تولید تصویر را در یک محصول واقعی پیاده‌سازی کنید، رعایت چند نکته می‌تواند عملکرد و پایداری سیستم را بهبود دهد.

API Key را در Frontend قرار ندهید

درخواست‌ها بهتر است از طریق Backend شما ارسال شوند تا کلید API در اختیار کاربران قرار نگیرد.

نتیجه را Cache کنید

اگر کاربران بارها یک تصویر مشابه تولید می‌کنند، می‌توانید خروجی را ذخیره کرده و در درخواست‌های بعدی مجدداً استفاده کنید.

این کار باعث کاهش هزینه و افزایش سرعت پاسخ می‌شود.

Promptها را اعتبارسنجی کنید

پیش از ارسال درخواست، ورودی کاربر را بررسی کنید.

برای مثال:

• جلوگیری از Prompt خالی
• محدود کردن طول متن
• حذف فاصله‌های اضافی
• جلوگیری از ارسال درخواست‌های تکراری

برای درخواست‌های طولانی Timeout تعیین کنید

تولید تصویر معمولاً بیشتر از Chat Completion زمان می‌برد.

بنابراین بهتر است Timeout مناسبی برای درخواست‌ها در نظر بگیرید.

خطاهای موقت را Retry کنید

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

از Queue برای درخواست‌های زیاد استفاده کنید

اگر کاربران زیادی هم‌زمان تصویر تولید می‌کنند، استفاده از صف (Queue) باعث افزایش پایداری سیستم می‌شود.

بهترین روش‌های نوشتن Prompt

کیفیت خروجی بیش از هر چیز به Prompt بستگی دارد.

یک Prompt حرفه‌ای معمولاً شامل این بخش‌هاست:

• سوژه اصلی
• سبک تصویر
• نورپردازی
• رنگ غالب
• زاویه دوربین
• کیفیت
• ترکیب‌بندی
• محدودیت‌ها

برای مثال:

A premium workspace with modern AI devices, cinematic lighting, ultra realistic photography, shallow depth of field, minimal design, dark navy colors, purple accents, no text

هرچه Prompt دقیق‌تر باشد، مدل نیز خروجی قابل پیش‌بینی‌تری تولید خواهد کرد.

نمونه پرامپت‌های کاربردی

کاور مقاله

A clean blog cover about artificial intelligence, dark navy background, futuristic gateway, purple glow, minimal design, no text

تصویر محصول

Professional product photography of wireless headphones on a white background with soft shadows, ultra realistic

رابط کاربری

Modern SaaS dashboard UI, glassmorphism, clean enterprise design, blue and purple color palette

تصویر تبلیغاتی

Premium marketing banner featuring artificial intelligence infrastructure, futuristic technology, modern composition, dramatic lighting

تصویر شبکه اجتماعی

Square social media illustration about AI automation, vibrant colors, clean composition, minimal background

اشتباهات رایج

بسیاری از کیفیت پایین تصاویر، به دلیل خطا در Prompt یا انتخاب نادرست پارامترهاست.

رایج‌ترین اشتباهات عبارت‌اند از:

Prompt بسیار کوتاه

مثال:

AI

این Prompt اطلاعات کافی به مدل نمی‌دهد.

Prompt بیش از حد مبهم

مثال:

A beautiful image

مدل دقیقاً نمی‌داند چه چیزی باید تولید کند.

انتخاب اندازه نامناسب

تولید تصویر مربعی برای استفاده به‌عنوان بنر افقی معمولاً نتیجه مطلوبی ایجاد نمی‌کند.

استفاده از کیفیت HD در تمام درخواست‌ها

همیشه نیازی به بالاترین کیفیت نیست.

برای پیش‌نمایش یا تصاویر آزمایشی، کیفیت استاندارد سریع‌تر و اقتصادی‌تر است.

استفاده مستقیم از API Key در مرورگر

این یکی از رایج‌ترین اشتباهات امنیتی است.

کلید API باید فقط در سمت سرور نگهداری شود.

تحلیل تصویر با API درواره (Vision / Image Input)

تاکنون یاد گرفتیم چگونه با استفاده از API درواره تصویر جدید تولید کنیم. اما بسیاری از پروژه‌های هوش مصنوعی تنها به تولید تصویر محدود نمی‌شوند.

در بسیاری از کاربردهای واقعی، لازم است مدل یک تصویر موجود را مشاهده، درک و تحلیل کند. این قابلیت که با نام‌های Vision، Image Understanding یا Image Input شناخته می‌شود، توسط مدل‌های چندوجهی (Multimodal Models) ارائه می‌شود.

در API درواره، تحلیل تصویر از طریق Chat Completions API انجام می‌شود. در این روش، تصویر در کنار متن پرسش برای مدل ارسال می‌شود و مدل در پاسخ، یک متن تولید می‌کند.

این قابلیت در سناریوهای متعددی کاربرد دارد، از جمله:

• توصیف محتوای تصویر
• استخراج متن از تصویر (OCR)
• تحلیل اسکرین‌شات رابط کاربری
• بررسی تصاویر محصولات فروشگاهی
• تولید Alt Text برای تصاویر وب‌سایت
• مقایسه دو یا چند تصویر
• تحلیل نمودارها و جداول
• تولید Prompt از روی یک تصویر مرجع

تفاوت تولید تصویر و تحلیل تصویر

اگر تازه با مدل‌های چندوجهی آشنا شده‌اید، ممکن است این دو قابلیت را با یکدیگر اشتباه بگیرید.

به عبارت دیگر:

اگر هدف شما ساخت یک تصویر جدید است، از Image Generation API استفاده می‌کنید.

اما اگر می‌خواهید مدل درباره یک تصویر موجود صحبت کند یا آن را تحلیل کند، باید از Chat Completions API استفاده کنید.

ساختار درخواست تحلیل تصویر

در Chat Completions، محتوای پیام کاربر می‌تواند شامل چند بخش باشد. این بخش‌ها در آرایه content قرار می‌گیرند و معمولاً از دو نوع تشکیل می‌شوند:

• متن (text)
• تصویر (image_url)

بهتر است ابتدا متن پرسش و سپس تصویر را ارسال کنید. این ترتیب باعث می‌شود مدل دقیقاً بداند از تصویر چه انتظاری دارید.

نمونه ساختار کلی درخواست:

{
  "model": "google/gemini-3-flash-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این تصویر را تحلیل کن."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ]
}

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

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

نمونه JavaScript:

const response = await fetch("https://api.darvareh.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DARVAREH_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "google/gemini-3-flash-preview",
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "این تصویر را به‌طور کامل توصیف کن."
          },
          {
            type: "image_url",
            image_url: {
              url: "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  })
});

const result = await response.json();

console.log(result.choices[0].message.content);

این روش برای تصاویر موجود در وب‌سایت، CDN یا فضای ذخیره‌سازی ابری بسیار مناسب است.

ارسال تصویر محلی با Base64

در بسیاری از پروژه‌ها، تصویر هنوز در اینترنت منتشر نشده است. برای مثال:

• تصویر توسط کاربر آپلود شده است.
• یک اسکرین‌شات از نرم‌افزار است.
• عکس در حافظه محلی قرار دارد.
• تصویر شامل اطلاعات محرمانه است.

در چنین شرایطی می‌توانید تصویر را به Base64 تبدیل کرده و به‌صورت Data URL ارسال کنید.

نمونه JavaScript:

import fs from "fs";

const image = fs.readFileSync("image.jpg");

const base64Image =
  `data:image/jpeg;base64,${image.toString("base64")}`;

سپس همین رشته را در image_url.url قرار دهید.

نمونه Python

import base64

with open("image.jpg","rb") as f:
    encoded = base64.b64encode(f.read()).decode()

image = f"data:image/jpeg;base64,{encoded}"

سپس مقدار image را در درخواست ارسال کنید.

ارسال چند تصویر در یک درخواست

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

برای این کار کافی است چند شیء image_url داخل آرایه content قرار دهید.

نمونه:

{
  "model": "google/gemini-3-flash-preview",
  "messages": [
    {
      "role":"user",
      "content":[
        {
          "type":"text",
          "text":"این دو تصویر را مقایسه کن."
        },
        {
          "type":"image_url",
          "image_url":{
            "url":"https://example.com/image1.jpg"
          }
        },
        {
          "type":"image_url",
          "image_url":{
            "url":"https://example.com/image2.jpg"
          }
        }
      ]
    }
  ]
}

مدل می‌تواند تفاوت‌ها، شباهت‌ها، تغییرات یا کیفیت دو تصویر را توضیح دهد.

کاربردهای واقعی Vision API

یکی از مزیت‌های مدل‌های چندوجهی، امکان استفاده از آن‌ها در طیف وسیعی از محصولات نرم‌افزاری است. در ادامه چند سناریوی پرکاربرد را بررسی می‌کنیم.

۱. تحلیل رابط کاربری (UI Review)

اگر در حال طراحی یک وب‌سایت یا اپلیکیشن هستید، می‌توانید اسکرین‌شات رابط کاربری را برای مدل ارسال کنید و از آن بخواهید مشکلات طراحی یا تجربه کاربری را شناسایی کند.

نمونه Prompt:

این اسکرین‌شات را از نظر طراحی رابط کاربری، خوانایی، فاصله‌گذاری، رنگ‌بندی و تجربه کاربری بررسی کن و پیشنهادهای بهبود ارائه بده.

۲. استخراج متن از تصویر

مدل‌های چندوجهی می‌توانند متن موجود در تصاویر را استخراج کرده و حتی آن را ترجمه یا بازنویسی کنند.

نمونه Prompt:

تمام متن‌های موجود در این تصویر را استخراج کن و نتیجه را به‌صورت منظم نمایش بده.

۳. تولید Alt Text برای SEO

اگر وب‌سایت یا فروشگاه اینترنتی دارید، می‌توانید برای هر تصویر به‌صورت خودکار متن جایگزین (Alt Text) تولید کنید.

نمونه Prompt:

برای این تصویر یک Alt Text فارسی کوتاه، دقیق و مناسب برای سئو بنویس.

۴. بررسی تصاویر محصولات

در فروشگاه‌های اینترنتی، مدل می‌تواند تصویر محصول را بررسی کرده و توضیحات مناسب برای صفحه محصول تولید کند.

نمونه Prompt:

این تصویر محصول را تحلیل کن و یک توضیح حرفه‌ای برای صفحه محصول بنویس.

۵. تحلیل نمودارها

اگر تصویر شامل نمودار یا جدول باشد، مدل می‌تواند روندها و داده‌های مهم را توضیح دهد.

نمونه Prompt:

این نمودار را تحلیل کن و مهم‌ترین روندها و نتایج آن را توضیح بده.

۶. تولید Prompt از روی تصویر

یکی از کاربردهای جالب Vision API، تولید Prompt برای بازسازی یا الهام گرفتن از یک تصویر است.

نمونه Prompt:

این تصویر را تحلیل کن و یک Prompt انگلیسی دقیق برای تولید تصویری مشابه بنویس.

این روش برای طراحان، تیم‌های تولید محتوا و متخصصان بازاریابی بسیار کاربردی است.

انتخاب بین URL و Base64

هر دو روش مزایا و کاربردهای خاص خود را دارند.

اگر تصویر روی اینترنت در دسترس است، استفاده از URL معمولاً انتخاب بهتری است.

اگر تصویر خصوصی است یا هنوز منتشر نشده، Base64 گزینه مناسب‌تری خواهد بود.

نکات مهم هنگام استفاده از Vision API

برای دستیابی به بهترین نتیجه، رعایت چند نکته ساده اما مهم توصیه می‌شود:

• متن پرسش را قبل از تصویر قرار دهید.
• درخواست خود را دقیق و شفاف بنویسید.
• از ارسال تصاویر بسیار بزرگ و غیرضروری خودداری کنید.
• اگر تنها بخشی از تصویر اهمیت دارد، در Prompt به آن اشاره کنید.
• برای تصاویر محرمانه، از Data URL (Base64) یا زیرساخت امن استفاده کنید.
• تنها از مدل‌هایی استفاده کنید که از ورودی تصویری پشتیبانی می‌کنند.

پرسش‌های متداول (FAQ)

API تولید تصویر در درواره چگونه کار می‌کند؟

درواره یک API سازگار با استاندارد OpenAI در اختیار توسعه‌دهندگان قرار می‌دهد که از طریق آن می‌توانید با ارسال یک Prompt متنی، توسط مدل انتخابی تصویر تولید کنید. تمام درخواست‌ها از طریق یک Base URL ثابت انجام می‌شوند و تنها کافی است مدل مناسب و پارامترهای موردنیاز را مشخص کنید.

آیا برای استفاده از API درواره باید مدل خاصی نصب کنم؟

خیر.

تمام پردازش‌ها در سمت سرویس انجام می‌شود و تنها کافی است از طریق HTTP درخواست خود را ارسال کنید.

برای استفاده از API به چه چیزی نیاز دارم؟

برای شروع کافی است:

• در درواره حساب کاربری ایجاد کنید.
• کیف پول خود را شارژ کنید.
• یک API Key بسازید.
• درخواست‌های خود را به آدرس API ارسال کنید.

آیا API درواره با OpenAI سازگار است؟

بله.

ساختار API درواره با استاندارد OpenAI سازگار است و بسیاری از کتابخانه‌ها و ابزارهایی که از OpenAI پشتیبانی می‌کنند، با تغییر Base URL و API Key قابل استفاده هستند. اما ممکن است تفاوت‌هایی داشته باشد.

آیا می‌توان بیش از یک تصویر تولید کرد؟

بله.

در مدل‌هایی که از این قابلیت پشتیبانی می‌کنند، با استفاده از پارامتر n می‌توانید چند تصویر را در یک درخواست تولید کنید.

چگونه اندازه تصویر را تغییر دهم؟

با استفاده از پارامتر size.

برای مثال:

{
  "size": "1536x1024"
}

البته اندازه‌های قابل پشتیبانی به مدل انتخابی بستگی دارند.

تفاوت کیفیت standard و hd چیست؟

کیفیت hd معمولاً تصاویر با جزئیات بیشتری تولید می‌کند، اما ممکن است هزینه و زمان تولید نیز افزایش یابد.

اگر کیفیت بسیار بالا نیاز ندارید، استفاده از standard انتخاب اقتصادی‌تری است.

تفاوت response_format=url و response_format=b64_json چیست؟

در حالت url، API آدرس تصویر تولیدشده را بازمی‌گرداند.

در حالت b64_json، تصویر به‌صورت رشته Base64 در پاسخ قرار می‌گیرد و می‌توانید آن را مستقیماً ذخیره یا پردازش کنید.

آیا می‌توان از تصاویر کاربران برای تحلیل استفاده کرد؟

بله.

اگر مدل انتخابی از ورودی تصویری پشتیبانی کند، می‌توانید تصویر را از طریق Chat Completions API ارسال کرده و از مدل بخواهید آن را تحلیل کند.

آیا می‌توان تصویر را با URL ارسال کرد؟

بله.

اگر تصویر روی اینترنت در دسترس باشد، استفاده از URL سریع‌تر و بهینه‌تر است.

آیا می‌توان تصویر محلی را ارسال کرد؟

بله.

در این حالت باید تصویر را به Base64 تبدیل کرده و به‌صورت Data URL ارسال کنید.

آیا می‌توان چند تصویر را هم‌زمان تحلیل کرد؟

بله.

در مدل‌هایی که از این قابلیت پشتیبانی می‌کنند، می‌توانید چند تصویر را در آرایه content قرار دهید و از مدل بخواهید آن‌ها را با یکدیگر مقایسه کند.

آیا Vision API می‌تواند متن داخل تصویر را بخواند؟

بله.

مدل‌های چندوجهی می‌توانند متن موجود در تصویر را استخراج کرده و درباره آن توضیح دهند یا آن را ترجمه و خلاصه کنند.

آیا می‌توان از Vision API برای تحلیل رابط کاربری استفاده کرد؟

بله.

یکی از کاربردهای رایج این قابلیت، بررسی اسکرین‌شات‌های رابط کاربری و دریافت پیشنهاد برای بهبود تجربه کاربری است.

آیا API درواره فقط برای تولید تصویر است؟

خیر.

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

آیا می‌توان از این API در اپلیکیشن موبایل استفاده کرد؟

بله.

API درواره مبتنی بر HTTP است و از هر زبان برنامه‌نویسی یا پلتفرمی که امکان ارسال درخواست HTTP را داشته باشد، قابل استفاده است.

آیا می‌توان از JavaScript و Python استفاده کرد؟

بله.

در این مقاله نمونه‌های کامل برای هر دو زبان ارائه شد و همین الگو را می‌توان در سایر زبان‌ها مانند PHP، Go، Java، C# و Ruby نیز به کار برد.

آیا تولید تصویر هزینه دارد؟

بله.

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

بهترین روش نگهداری API Key چیست؟

کلید API را فقط در سمت سرور نگهداری کنید و هرگز آن را مستقیماً در کد Frontend یا اپلیکیشن منتشرشده قرار ندهید.

از کجا می‌توان مستندات کامل API را مشاهده کرد؟

تمام جزئیات مربوط به API، مدل‌ها و نمونه درخواست‌ها در مستندات رسمی درواره در دسترس است.

بهترین روش‌ها (Best Practices)

اگر قصد دارید قابلیت تولید یا تحلیل تصویر را در یک محصول واقعی پیاده‌سازی کنید، رعایت توصیه‌های زیر می‌تواند امنیت، عملکرد و تجربه کاربری بهتری ایجاد کند.

۱. API Key را محرمانه نگه دارید

کلید API باید فقط در Backend نگهداری شود و هرگز در کد Frontend، اپلیکیشن موبایل یا مخزن عمومی قرار نگیرد.

۲. Promptهای کاربران را اعتبارسنجی کنید

قبل از ارسال درخواست، Prompt را از نظر خالی بودن، طول متن و داده‌های نامعتبر بررسی کنید.

۳. اندازه تصویر را متناسب با کاربرد انتخاب کنید

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

۴. از Base64 فقط در صورت نیاز استفاده کنید

اگر تصویر در یک URL عمومی در دسترس است، استفاده از response_format=url معمولاً بهینه‌تر از دریافت Base64 خواهد بود.

۵. خروجی‌های تکراری را Cache کنید

اگر کاربران Promptهای مشابه ارسال می‌کنند، ذخیره و استفاده مجدد از خروجی‌ها می‌تواند هزینه و زمان پاسخ را کاهش دهد.

۶. برای Vision از تصاویر باکیفیت استفاده کنید

هرچه تصویر واضح‌تر و با وضوح مناسب‌تری ارسال شود، تحلیل مدل نیز دقیق‌تر خواهد بود.

۷. برای تصاویر حساس از URL عمومی استفاده نکنید

اگر تصویر حاوی اطلاعات محرمانه است، آن را به‌صورت Base64 یا از طریق زیرساخت امن ارسال کنید.

جمع‌بندی

مدل‌های تولید تصویر، توسعه قابلیت‌های خلاقانه در نرم‌افزارها را بسیار ساده‌تر کرده‌اند. با استفاده از API درواره می‌توانید تنها با یکپارچه‌سازی یک API سازگار با استاندارد OpenAI، تصاویر جدید تولید کنید یا از مدل‌های چندوجهی برای تحلیل تصاویر موجود بهره ببرید.

در این مقاله با ساختار Image Generation API، پارامترهای اصلی، نمونه‌کدهای JavaScript و Python، روش‌های دریافت تصویر، تحلیل تصویر با Vision API و مجموعه‌ای از بهترین روش‌های پیاده‌سازی آشنا شدیم.

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

مقالات مرتبط

برای آشنایی بیشتر با اکوسیستم هوش مصنوعی و APIهای درواره، مطالعه مقالات زیر نیز پیشنهاد می‌شود:

• آموزش اتصال Cursor به API درواره
• آموزش اتصال OpenClaw به API درواره
• Function Calling چیست و چگونه کار می‌کند؟
• Structured Outputs چیست؟
• AI Router چیست؟
• OpenAI-Compatible API چیست؟
• آموزش کامل استفاده از API درواره