Image Variation

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

POST /v1/images/variations

اطلاع

Variation یعنی ساخت نسخه‌های تازه از تصویر مرجع. اگر هدف شما تغییر مشخص یک بخش تصویر است، Image Edit دقیق‌تر است.

هشدار

در OpenAI، مسیر POST /v1/images/variations فقط با dall-e-2 پشتیبانی می‌شود. برای مدل‌های GPT Image مثل gpt-image-1 یا gpt-image-1.5، از Image Edit یا تولید تصویر با تصویر مرجع استفاده کنید.

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

از Image Variation استفاده کنید وقتی می‌خواهید:

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

برای ساخت تصویر کاملاً تازه از متن، Image Generation مسیر مناسب‌تری است.

شروع سریع

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

with open("reference.png", "rb") as image:
  response = requests.post(
      "https://YOUR_WORKSPACE.godarai.ir/v1/images/variations",
      headers={"Authorization": "Bearer YOUR_GODARAI_TOKEN"},
      data={
          "model": "openai:default:dall-e-2",
          "n": "2",
          "size": "1024x1024",
          "response_format": "url",
      },
      files={"image": ("reference.png", image, "image/png")},
      timeout=180,
  )

response.raise_for_status()
for item in response.json()["data"]:
  print(item["url"])

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("model", "openai:default:dall-e-2");
form.append("n", "2");
form.append("size", "1024x1024");
form.append("response_format", "url");
form.append(
"image",
new Blob([await readFile("reference.png")], { type: "image/png" }),
"reference.png",
);

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/images/variations", {
method: "POST",
headers: {
  Authorization: "Bearer YOUR_GODARAI_TOKEN",
},
body: form,
});

if (!response.ok) {
throw new Error("Request failed with status " + response.status);
}

const variations = await response.json();
for (const item of variations.data) {
console.log(item.url);
}

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/images/variations" --header "Authorization: Bearer YOUR_GODARAI_TOKEN" --form "model=openai:default:dall-e-2" --form "n=2" --form "size=1024x1024" --form "response_format=url" --form "image=@reference.png;type=image/png"

from openai import OpenAI

client = OpenAI(
  api_key="YOUR_GODARAI_TOKEN",
  base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

with open("reference.png", "rb") as image:
  response = client.images.create_variation(
      model="openai:default:dall-e-2",
      image=image,
      n=2,
      size="1024x1024",
      response_format="url",
  )

for item in response.data:
  print(item.url)

import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
apiKey: "YOUR_GODARAI_TOKEN",
baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.images.createVariation({
model: "openai:default:dall-e-2",
image: new File([await readFile("reference.png")], "reference.png", { type: "image/png" }),
n: 2,
size: "1024x1024",
response_format: "url",
});

for (const item of response.data) {
console.log(item.url);
}

در بیشتر سناریوها، ارسال فایل با multipart/form-data برای Variation طبیعی‌تر از ارسال JSON است.

برای OpenAI، تصویر مرجع باید فایل PNG معتبر، مربع و کمتر از ۴MB باشد. اگر تصویر شما JPEG، مستطیلی یا بزرگ‌تر است، پیش از ارسال آن را آماده کنید.

نکته

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

ساختار درخواست

فیلدهای رایج:

فیلد	کاربرد
`model`	شناسه مدل تصویری مجاز.
`image`	تصویر مرجع برای ساخت نسخه‌های جدید.
`n`	تعداد نسخه‌های خروجی.
`size`	اندازه خروجی، اگر مدل پشتیبانی کند.
`response_format`	فرمت پاسخ در مدل‌هایی که پشتیبانی می‌کنند؛ برای `dall-e-2` می‌تواند `url` یا `b64_json` باشد.

هشدار

OpenAI برای Variation تصویر مرجع را به‌صورت فایل در multipart/form-data می‌پذیرد. شکل JSON برای تصویر مرجع به ارائه‌دهنده و مدل بستگی دارد و نباید برای مسیر OpenAI فرض شود.

خروجی

{
  "created": 1720000000,
  "data": [
    {
      "url": "https://YOUR_WORKSPACE.godarai.ir/assets/variation-1.png"
    },
    {
      "url": "https://YOUR_WORKSPACE.godarai.ir/assets/variation-2.png"
    }
  ]
}

اگر response_format را b64_json بفرستید، خروجی می‌تواند داده base64 باشد. اگر URL می‌گیرید، آن را برای نگهداری بلندمدت به storage خود منتقل کنید؛ URLهای ارائه‌دهنده معمولاً برای دسترسی دائمی طراحی نشده‌اند.

تفاوت Variation با Edit

موضوع	Image Variation	Image Edit
هدف	ساخت نسخه‌های مشابه یا خلاقانه	تغییر هدفمند تصویر
ورودی اصلی	تصویر مرجع	تصویر ورودی و پرامپت تغییر
کنترل ناحیه	معمولاً کمتر	با `mask` می‌تواند دقیق‌تر باشد
خروجی	چند گزینه نزدیک به تصویر پایه	نسخه ویرایش‌شده طبق دستور

اگر کاربر نهایی انتظار تغییر دقیق دارد، Variation انتخاب مناسبی نیست.

کیفیت تصویر مرجع

کیفیت خروجی به تصویر مرجع وابسته است. برای نتیجه بهتر:

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

هزینه و پایش

هر مقدار بالاتر n معمولاً یعنی خروجی بیشتر، زمان بیشتر و هزینه بیشتر. گدارAI در تخمین اولیه تعداد خروجی و تصویر ورودی را لحاظ می‌کند و اگر ارائه‌دهنده در پاسخ usage یا هزینه دقیق برگرداند، مصرف نهایی را با همان داده ثبت می‌کند. پس برای جریان‌های پرترافیک:

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

خطاهای رایج

نشانه	علت محتمل	راه‌حل
`model is required`	شناسه مدل ارسال نشده است.	مدل تصویری مجاز را وارد کنید.
`image is required`	تصویر مرجع ارسال نشده است.	تصویر را در `multipart/form-data` با فیلد `image` بفرستید.
خطای مدل درباره `dall-e-2`	در OpenAI، `images/variations` فقط `dall-e-2` را می‌پذیرد.	برای Variation از `openai:default:dall-e-2` استفاده کنید یا برای GPT Image به `Image Edit` بروید.
درخواست با خطای دسترسی رد می‌شود	مدل برای نوع تصویر مجاز نیست.	مدل نوع `image_generation` انتخاب کنید.
خروجی خیلی از تصویر مرجع دور است	مدل یا تنظیمات Variation کنترل کافی ندارد.	مدل دیگری آزمایش کنید یا اگر تغییر دقیق می‌خواهید از `Image Edit` استفاده کنید.
خطای فایل	فرمت، اندازه یا روش ارسال فایل سازگار نیست.	برای OpenAI فایل PNG مربع و کمتر از ۴MB بفرستید.

جمع‌بندی

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

چه زمانی استفاده کنیم؟​

شروع سریع​

ساختار درخواست​

خروجی​

تفاوت Variation با Edit​

کیفیت تصویر مرجع​

هزینه و پایش​

خطاهای رایج​

جمع‌بندی​