Image Edit

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

POST /v1/images/edits

اطلاع

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

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

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

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

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

شروع سریع با فایل

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import base64
import requests

with open("sample.png", "rb") as image:
  response = requests.post(
      "https://YOUR_WORKSPACE.godarai.ir/v1/images/edits",
      headers={"Authorization": "Bearer YOUR_GODARAI_TOKEN"},
      data={
          "model": "openai:default:gpt-image-1",
          "prompt": "پس‌زمینه تصویر را ساده‌تر و روشن‌تر کن، اما سوژه اصلی را تغییر نده.",
          "size": "1024x1024",
          "output_format": "png",
      },
      files={"image[]": ("sample.png", image, "image/png")},
      timeout=180,
  )

response.raise_for_status()
image_bytes = base64.b64decode(response.json()["data"][0]["b64_json"])
with open("edited.png", "wb") as output:
  output.write(image_bytes)

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

const form = new FormData();
form.append("model", "openai:default:gpt-image-1");
form.append("prompt", "پس‌زمینه تصویر را ساده‌تر و روشن‌تر کن، اما سوژه اصلی را تغییر نده.");
form.append("size", "1024x1024");
form.append("output_format", "png");
form.append(
"image[]",
new Blob([await readFile("sample.png")], { type: "image/png" }),
"sample.png",
);

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

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

const editedImage = await response.json();
await writeFile("edited.png", Buffer.from(editedImage.data[0].b64_json, "base64"));

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/images/edits" --header "Authorization: Bearer YOUR_GODARAI_TOKEN" --form "model=openai:default:gpt-image-1" --form "prompt=پس‌زمینه تصویر را ساده‌تر و روشن‌تر کن، اما سوژه اصلی را تغییر نده." --form "size=1024x1024" --form "output_format=png" --form "image[]=@sample.png;type=image/png" | jq -r '.data[0].b64_json' | base64 --decode > edited.png

import base64
from openai import OpenAI

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

with open("sample.png", "rb") as image:
  response = client.images.edit(
      model="openai:default:gpt-image-1",
      image=image,
      prompt="پس‌زمینه تصویر را ساده‌تر و روشن‌تر کن، اما سوژه اصلی را تغییر نده.",
      size="1024x1024",
      output_format="png",
  )

image_bytes = base64.b64decode(response.data[0].b64_json)
with open("edited.png", "wb") as output:
  output.write(image_bytes)

import { readFile, writeFile } 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.edit({
model: "openai:default:gpt-image-1",
image: new File([await readFile("sample.png")], "sample.png", { type: "image/png" }),
prompt: "پس‌زمینه تصویر را ساده‌تر و روشن‌تر کن، اما سوژه اصلی را تغییر نده.",
size: "1024x1024",
output_format: "png",
});

await writeFile("edited.png", Buffer.from(response.data[0].b64_json, "base64"));

این روش معمولاً با multipart/form-data ارسال می‌شود و برای فایل واقعی انتخاب طبیعی‌تری است. برای سازگاری با مدل‌های GPT Image، فیلد فایل را می‌توانید با نام image[] بفرستید؛ گدارAI فیلد image را هم برای مسیرهای سازگار می‌پذیرد.

ارسال با JSON

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

{
  "model": "xai:default:grok-imagine-image",
  "prompt": "نور تصویر را طبیعی‌تر کن.",
  "image": {
    "type": "image_url",
    "url": "https://YOUR_WORKSPACE.godarai.ir/assets/input-image.png"
  },
  "response_format": "url"
}

هشدار

نشانی تصویر باید برای ارائه‌دهنده مدل قابل دسترس باشد. اگر فایل پشت شبکه خصوصی، نشست کاربری یا لینک موقت کوتاه‌عمر باشد، درخواست ممکن است خطا بدهد یا نتیجه ناپایدار شود. برای مدل‌های GPT Image، ارسال فایل با multipart/form-data معمولاً مسیر مطمئن‌تری است.

`mask` چه زمانی لازم است؟

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

نمونه کاربرد:

تغییر رنگ یک شیء خاص.
حذف یک بخش مزاحم.
جایگزینی پس‌زمینه بدون تغییر سوژه اصلی.

نکته

اگر ویرایش باید دقیق باشد، پرامپت را موضعی بنویسید: بگویید کدام بخش تغییر کند و کدام بخش دست‌نخورده بماند.

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

فیلدهای رایج

فیلد	کاربرد
`model`	شناسه مدل تصویری مجاز.
`image`	تصویر ورودی؛ فایل، نشانی یا ساختار وابسته به مدل.
`prompt`	توضیح تغییر مورد نظر.
`mask`	ناحیه مجاز برای ویرایش.
`size`	اندازه خروجی، اگر مدل پشتیبانی کند.
`output_format`	فرمت فایل خروجی در مدل‌های GPT Image، مثل `png`، `jpeg` یا `webp`.
`output_compression`	فشرده‌سازی خروجی برای `jpeg` یا `webp`، اگر مدل پشتیبانی کند.
`background`	نوع پس‌زمینه خروجی، اگر مدل پشتیبانی کند.
`input_fidelity`	میزان حفظ جزئیات تصویر ورودی در مدل‌هایی که این فیلد را می‌پذیرند.
`response_format`	فرمت خروجی در مدل‌هایی که از آن پشتیبانی می‌کنند؛ برای مدل‌های جدید GPT Image معمولاً از `b64_json` استفاده کنید.

خروجی

پاسخ مدل‌های GPT Image معمولاً شبیه خروجی تولید تصویر و شامل داده base64 است:

{
  "created": 1720000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 1056,
    "total_tokens": 2256
  }
}

در بعضی ارائه‌دهنده‌ها یا مدل‌های قدیمی‌تر، خروجی می‌تواند نشانی تصویر باشد:

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

اگر b64_json می‌گیرید، اپلیکیشن شما باید آن را به فایل تبدیل و در storage مناسب ذخیره کند.

حریم خصوصی فایل ورودی

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

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

هزینه و پایش

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

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

خطاهای رایج

نشانه	علت محتمل	راه‌حل
`model is required`	مدل ارسال نشده است.	شناسه مدل تصویری مجاز را وارد کنید.
`prompt is required`	توضیح تغییر ارسال نشده است.	فیلد `prompt` را با توضیح روشن تغییر مورد نظر بفرستید.
`image is required`	تصویر ورودی ارسال نشده است.	فایل را با `image[]` یا `image` در `multipart/form-data` بفرستید.
`Model access denied or unsupported for image generation`	مدل برای تصویر مجاز نیست.	مدل نوع `image_generation` انتخاب کنید.
خطای `unsupported content type`	نوع بدنه درخواست پشتیبانی نمی‌شود.	از `application/json` یا `multipart/form-data` استفاده کنید.
خطای ارائه‌دهنده درباره `mask`	فایل ماسک با تصویر هم‌اندازه یا هم‌فرمت نیست، یا کانال آلفا ندارد.	ماسک را با همان اندازه و فرمت تصویر اصلی و همراه کانال آلفا بسازید.
خروجی با خواسته شما فاصله دارد	پرامپت یا ماسک مبهم است.	پرامپت را موضعی‌تر کنید و در صورت نیاز `mask` بدهید.

جمع‌بندی

Image Edit برای تغییر هدفمند تصویر موجود است. با فایل تمیز، پرامپت دقیق، مدل تصویری مجاز و بررسی هزینه/رخداد، می‌توانید ویرایش تصویر را در محصول خود قابل کنترل‌تر پیاده کنید.

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

شروع سریع با فایل​

ارسال با JSON​

mask چه زمانی لازم است؟​

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

خروجی​

حریم خصوصی فایل ورودی​

هزینه و پایش​

خطاهای رایج​

جمع‌بندی​