تولید تصویر

یاد بگیرید چگونه با استفاده از مدل‌های موجود از طریق API AvalAI، از جمله GPT Image، مدل‌های تصویری Gemini، Qwen image، Seedream، FLUX، Cloudflare، Runway و Imagen، تصویر تولید یا ویرایش کنید.

مقدمه

API تصویر AvalAI نقاط پایانی برای ایجاد تصویر فراهم می‌کند:

• تولیدات (Generations): ایجاد تصاویر از ابتدا بر اساس یک پرامپت متنی.
• ویرایش‌ها (Edits): ویرایش تصاویر موجود بر اساس پرامپت جدید، تصویر مرجع یا ماسک، وقتی مدل انتخابی از ویرایش پشتیبانی می‌کند.
• تغییرات (Variations): ایجاد نسخه‌های جایگزین از تصویر موجود، وقتی مدل انتخابی از variations پشتیبانی می‌کند.

این راهنما استفاده از این قابلیت‌ها را از طریق AvalAI پوشش می‌دهد.

انتخاب Endpoint مناسب

• وقتی یک درخواست مستقیم تولید یا ویرایش تصویر می‌خواهید و می‌خواهید مدل تصویر را خودتان انتخاب کنید، از v1/images/generations یا v1/images/edits استفاده کنید.
• فقط زمانی از v1/responses استفاده کنید که مدل انتخابی و مسیر AvalAI از ابزار image generation داخل یک مکالمه یا flow چندمرحله‌ای پشتیبانی کند.
• برای تجربه‌های ویرایش تصویر چندنوبتی، شناسه تصویر تولیدشده یا فایل مرجع را در state برنامه نگه دارید تا نوبت بعدی دقیقا همان تصویر را هدف بگیرد.

مسیر مهاجرت ابزار تصویر در Responses

OpenAI دو مسیر تصویر را مستند می‌کند: Image API مستقیم برای تولید یا ویرایش تک‌مرحله‌ای، و ابزار image-generation در Responses API برای گردش‌کارهای مکالمه‌ای یا چندمرحله‌ای. در AvalAI، v1/images/generations و v1/images/edits را پیش‌فرض production نگه دارید مگر اینکه مدل /v1/responses و حساب شما صریحا از ابزار میزبانی‌شده image_generation پشتیبانی کند.

گردش‌کار فعلی Image API	معادل Responses API	راهنمای AvalAI
تولید یک تصویر با gpt-image-2	tools=[{"type": "image_generation"}] روی مدل Responses مثل gpt-5.5	برای کارهای ساده Image API را ترجیح دهید؛ وقتی تصویر بخشی از chat یا agent flow است از Responses استفاده کنید.
نمایش پیشرفت با streaming در Image API	stream=True همراه partial_images روی tool	این قابلیت را وابسته به route بدانید و اگر فعال نبود به endpointهای مستقیم تصویر برگردید.
ویرایش با تصویر/ماسک آپلودشده	ارسال file ID یا image input به Responses و تنظیم action="edit" در صورت پشتیبانی	برای ویرایش و masking قابل‌تکرار، /v1/images/edits را نگه دارید.
نگه‌داری خروجی در state برنامه	استفاده از previous_response_id یا ذخیره شناسه تصویر/tool call	شناسه‌ها یا مسیر فایل ذخیره‌شده را نگه دارید تا نوبت بعدی همان تصویر را هدف بگیرد.

هنگام استفاده از ابزار Responses، مقدار action را آگاهانه تنظیم کنید: auto اجازه می‌دهد مدل خودش بین تولید یا ویرایش تصمیم بگیرد، generate تولید تصویر جدید را اجباری می‌کند و edit را فقط وقتی استفاده کنید که تصویر در context وجود دارد. برای اینکه در routeهای پشتیبانی‌شده مدل حتما ابزار را فراخوانی کند، از tool_choice={"type": "image_generation"} استفاده کنید؛ در غیر این صورت ممکن است مدل به‌جای تصویر، پاسخ متنی بدهد.

در فیلد model مربوط به Responses از مدل GPT Image مثل gpt-image-2 استفاده نکنید. ابزار تصویر در Responses توسط یک مدل mainline متنی مثل gpt-5.5 فراخوانی می‌شود و سپس ابزار hosted backend مناسب GPT Image را انتخاب می‌کند. انتخاب صریح gpt-image-2، gpt-image-1.5، gpt-image-1 یا gpt-image-1-mini مربوط به فراخوانی مستقیم Image API است.

from openai import OpenAI
import base64
import os

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="Draw a clean product hero image of a matte black smart speaker on a walnut desk.",
    tools=[
        {
            "type": "image_generation",
            "quality": "medium",
            "size": "1024x1024",
        }
    ],
)

image_calls = [item for item in response.output if item.type == "image_generation_call"]

if not image_calls:
    raise RuntimeError(
        "No image was generated. Confirm Responses image-tool support or use /v1/images/generations."
    )

with open("responses-product-hero.png", "wb") as image_file:
    image_file.write(base64.b64decode(image_calls[0].result))

print("Revised prompt:", getattr(image_calls[0], "revised_prompt", None))

اگر ابزار میزبانی‌شده برای route شما فعال نبود، Image API مستقیم را استفاده کنید، تصویر تولیدشده را ذخیره کنید و URL، file ID یا metadata آن را در نوبت بعدی /v1/responses به‌عنوان context برنامه ارسال کنید.

Endpointهای فعلی GPT Image در AvalAI

مدل‌های فعال OpenAI GPT Image در data/models.json در حال حاضر این routeهای مستقیم Image API را ارائه می‌کنند:

مدل	تولید مستقیم	ویرایش مستقیم	نکته
gpt-image-2	بله	بله	انتخاب پیش‌فرض برای workflowهای جدید تولید و ویرایش تصویر با کیفیت بالا.
gpt-image-1.5	بله	خیر	برای workflowهای نسل قبلی که فقط generation لازم دارند نگه دارید و کیفیت و هزینه را مقایسه کنید.
gpt-image-1	بله	بله	route پایدار قدیمی‌تر برای اپلیکیشن‌های موجود تصویر.
gpt-image-1-mini	بله	بله	گزینه کم‌هزینه‌تر برای draft، ایده‌پردازی حجیم و ویرایش‌های ساده.

این جدول routeهای مستقیم /v1/images/* در AvalAI را توصیف می‌کند. پشتیبانی ابزار تصویر در Responses جداگانه است و باید برای هر حساب، route و مدل mainline انتخابی بررسی شود.

نکته مهم

برای بهترین نتایج، توصیه می‌شود از پرامپت‌های انگلیسی استفاده کنید زیرا مدل‌های تولید تصویر معمولا برای زبان انگلیسی بهینه‌سازی شده‌اند. برای پشتیبانی فنی یا سوالات، با t.me/AvalAISupport تماس بگیرید.

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

AvalAI دسترسی به مدل‌های مختلف تولید تصویر را فراهم می‌کند. قابلیت‌ها (مانند ویرایش/تغییرات) و کیفیت می‌تواند متفاوت باشد:

• GPT Image 2: پیشنهاد پیش‌فرض OpenAI برای گردش‌کارهای جدید تولید و ویرایش تصویر با کیفیت بالا. برای تصویرهای prompt-heavy، متن داخل تصویر، mockup رابط کاربری، infographic، product shot، compositing و ویرایش‌هایی که حفظ identity، layout یا label مهم است استفاده کنید. برای playbook پرامپت‌نویسی الهام‌گرفته از Cookbook، تولید تصاویر با مدل‌های GPT Image را ببینید.
• GPT Image 1.5: مدل پیشرفته قبلی OpenAI برای تولید و ویرایش تصویر. برای گردش‌کارهای validate شده قدیمی نگه دارید تا قبل از مهاجرت به GPT Image 2، کیفیت خروجی، تعداد retry و هزینه را مقایسه کنید.
• GPT Image 1 و GPT Image 1 Mini: مدل‌های قدیمی‌تر GPT Image. GPT Image 1 Mini هنوز برای draftهای کم‌هزینه و ideation با حجم بالا مفید است.
• Seedream 5.0: مدل پیشرفته تولید و ویرایش تصویر ByteDance با قابلیت‌های منحصر به فرد:
  • seedream-5-0-260128: مدل پیشرفته با پشتیبانی از تولید تصویر متوالی (تا 15 تصویر مرتبط)، ترکیب چند تصویر، خروجی جریانی و تولید با وضوح بالا تا 4K. دارای پردازش دسته‌ای هوشمند و پشتیبانی از تبدیل متن-به-تصویر و ویرایش تصویر-به-تصویر. برای نمونه‌های کاربرد تفصیلی به راهنمای جامع ما مراجعه کنید.
• مدل‌های Google Imagen 4.0 جدیدترین مدل‌های تولید تصویر گوگل با کیفیت و جزئیات استثنایی:
• imagen-4.0-ultra-generate-001: تولید تصویر با کیفیت فوق‌العاده بالا با جزئیات و واقع‌گرایی استثنایی، پشتیبانی از وضوح‌های تا 2816x1536.
• imagen-4.0-generate-001: تولید تصویر حرفه‌ای با کیفیت بالا با پشتیبانی از وضوح‌های تا 2048x2048.
• imagen-4.0-fast-generate-001: تولید تصویر سریع بهینه‌سازی شده برای سرعت با حفظ کیفیت.
• imagen-3.0-generate-002: نسخه به‌روزرسانی شده Imagen 3.0 با قابلیت‌های پیشرفته.
• imagen-3.0-generate-001: مدل پایه Imagen 3.0 برای تولید تصاویر با کیفیت بالا.
• imagen-3.0-fast-generate-001: نسخه سریع‌تر بهینه‌سازی شده برای کاهش تاخیر با حفظ کیفیت خوب.
• مدل‌های BFL (FLUX): مدل‌های پیشرفته تولید و ویرایش تصویر از Black Forest Labs:
• flux.2-pro: پیشرفته‌ترین مدل FLUX با کیفیت تصویر برتر و قیمت‌گذاری بر اساس مگاپیکسل. مگاپیکسل اول: $0.03، مگاپیکسل‌های اضافی: $0.015، تصویر مرجع: $0.015/MP. بهترین برای تولید تصویر با کیفیت حرفه‌ای. نکته: فقط برای پرامپت‌های انگلیسی بهینه شده است.
• flux-1.1-pro: مدل تولید تصویر پیشرفته با عملکرد برتر در کیفیت تصویر، پیروی از پرامپت، و سرعت تولید.
• flux.1-kontext-pro: مدل همه‌کاره که از هم تولید و هم ویرایش پشتیبانی می‌کند، در وظایف ویرایش متن و حفظ شخصیت عالی است.
• مدل‌های تصویر Alibaba Qwen: مدل‌های پیشرفته تولید و ویرایش تصویر با پشتیبانی دوگانه SDK:
  • qwen-image-2.0-pro: تولید تصویر حرفه‌ای با تایپوگرافی پیشرفته که خطای رندر متن را به نزدیک صفر در بیش از ۴۰ زبان کاهش می‌دهد. خروجی با رزولوشن بومی ۲K ایده‌آل برای اینفوگرافیک‌ها و محتوای بصری پیچیده. قیمت: ۰.۰۶ دلار/تصویر.
  • qwen-image-2.0: مدل تولید و ویرایش یکپارچه با فوتورئالیسم بهبودیافته و رندر متن قابل اعتماد. رزولوشن بومی ۲K با خروجی با کیفیت حرفه‌ای. قیمت: ۰.۰۴ دلار/تصویر.
  • z-image-turbo: تولید فوق‌سریع تصویر با حالت اختیاری Thinking برای کیفیت بهتر. حالت سریع پیش‌فرض (۰.۰۱۵ دلار/تصویر) یا حالت Thinking (۰.۰۳ دلار/تصویر) برای صحنه‌های پیچیده.
  • qwen-image-edit-plus: ویرایش پیشرفته تصویر با کیفیت بهبودیافته نسبت به qwen-image-edit اصلی. از هر دو نقطه پایانی v1/images/generations و v1/images/edits پشتیبانی می‌کند. قیمت: ۰.۰۳ دلار/تصویر.
  • qwen-image: تولید حرفه‌ای متن-به-تصویر با بهبود هوشمند prompt، پشتیبانی از نسبت‌های مختلف ابعاد و پارامترهای پیشرفته.
  • qwen-image-edit: قابلیت‌های پیچیده ویرایش تصویر با پشتیبانی ورودی چند تصویری و کنترل دقیق اصلاحات. برای جزئیات در مورد مدل‌های تصویر خاص موجود از طریق AvalAI و ویژگی‌های آن‌ها، به بررسی اجمالی مدل‌ها مراجعه کنید.

راهنمای GPT Image بالا با اقتباس از OpenAI Cookbook رسمی و openai/openai-cookbook، با جزئیات مدل و endpoint مخصوص AvalAI تهیه شده است.

الگوی پرامپت برای تصویرهای production

برای assetهای production، پرامپت را مثل brief ساختاریافته بنویسید:

Goal: تصویر کجا استفاده می‌شود
Format: photo, ad, slide, UI mockup, infographic, diagram, product shot
Canvas: اندازه، جهت، نسبت تصویر
Subject: شیء، شخص، صحنه یا interface اصلی
Composition: کادربندی، زاویه دید، جای‌گذاری، whitespace
Style: photorealistic, editorial, flat vector, 3D render, ...
Text: متن دقیق داخل کوتیشن، جایگاه، تایپوگرافی، زبان
Constraints: no watermark, no extra text, preserve logo/layout/colors

برای draft سریع از quality="low"، برای استفاده عمومی از quality="medium" و برای متن شلوغ، infographic، product close-up، ویرایش حساس به identity یا asset نهایی مشتری از quality="high" استفاده کنید.

در ویرایش‌ها، هم تغییر و هم invariantها را مشخص کنید:

Change only the wall color to warm white.
Keep the sofa, table, lighting, shadows, camera angle, floor texture,
object positions, and image crop exactly the same.

استفاده از ارائه‌دهندگان غیر OpenAI با پارامترهای مخصوص ارائه دهنده

هنگام استفاده از مدل‌های تولید تصویر از ارائه‌دهندگانی غیر از OpenAI (مانند Black Forest Labs، Alibaba، BytePlus، Cloudflare یا Google)، ممکن است نیاز داشته باشید پارامترهای مخصوص ارائه دهنده را ارسال کنید که به طور مستقیم توسط کتابخانه کلاینت OpenAI پشتیبانی نمی‌شوند. AvalAI دو روش برای این کار ارائه می‌دهد:

استفاده از پارامتر extra_body

روش استاندارد استفاده از پارامتر extra_body است. سیستم به طور خودکار این پارامترهای مخصوص ارائه‌دهنده را به ارائه‌دهنده مناسب نگاشت می‌کند زیرا اینها پارامترهای استاندارد OpenAI نیستند.

پارامترهای مخصوص ارائه‌دهنده رایج

در اینجا چند نمونه از پارامترهای مخصوص ارائه‌دهنده برای مدل‌های تصویری پشتیبانی‌شده آورده شده است:

• output_format - تعیین فرمت خروجی برای تصویر تولید شده
• aspect_ratio - کنترل نسبت ابعاد تصاویر تولید شده
• prompt_upsampling - فعال یا غیرفعال کردن بهبود پرامپت
• safety_tolerance - تنظیم فیلتر ایمنی محتوا
• samples - تعداد نمونه‌های تولیدی
• extras - گزینه‌های اضافی مخصوص مدل
• image_strength - کنترل قدرت تولید تصویر به تصویر
• init_image_mode - تنظیم حالت مقداردهی اولیه برای ویرایش تصویر
• init_image - ارائه تصویر اولیه برای ویرایش

# مثال پایتون با استفاده از مدل Black Forest Labs با پارامترهای مخصوص ارائه دهنده
response = client.images.generate(
    model="flux-1.1-pro",
    prompt="اژدهای باشکوهی که در میان ابرها پرواز می‌کند",
    size="1024x1024",
    extra_body={
        "aspect_ratio": "16:9",
        "output_format": "png",
        "safety_tolerance": 2,
        "prompt_upsampling": True,
    },
)

پارامتر extra_body به شما امکان می‌دهد هر پارامتر اضافی مورد نیاز توسط ارائه دهنده خاص را ارسال کنید. این دیکشنری باید در بدنه درخواست (body) ارسال شود.

استفاده مستقیم از پارامترهای مستندنشده (جاوااسکریپت/تایپ‌اسکریپت)

برای کاربران تایپ‌اسکریپت، می‌توانید پارامترهای مستندنشده را با استفاده از // @ts-expect-error به صورت مستقیم ارسال کنید:

// مثال جاوااسکریپت/تایپ‌اسکریپت با استفاده از پارامترهای مستندنشده به صورت مستقیم
const response = await client.images.generate({
  model: "flux.2-pro",
  prompt: "A detailed landscape with mountains and a lake at sunset",
  size: "1024x1024",
  // @ts-expect-error provider-specific parameters pass through to AvalAI
  extra_body: {
    aspect_ratio: "16:9",
    output_format: "png",
    safety_tolerance: 2,
    prompt_upsampling: true,
  },
  response_format: "url",
});

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

اگر می‌خواهید آرگومان‌های اضافی را به صورت صریح ارسال کنید، می‌توانید از گزینه‌های درخواست query، body و headers نیز استفاده کنید.

مدل‌های تصویر Alibaba Qwen

مدل‌های تصویر Qwen پشتیبانی دوگانه منحصر به فردی از SDK ارائه می‌دهند که به شما امکان استفاده از هم فرمت سازگار با OpenAI و هم فرمت بومی Alibaba Dashscope را برای حداکثر انعطاف‌پذیری و دسترسی به ویژگی‌های پیشرفته می‌دهد.

استفاده از فرمت OpenAI SDK

# مثال پایتون با استفاده از مدل‌های Qwen با فرمت OpenAI SDK
import os
from openai import OpenAI

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

# تولید متن-به-تصویر
response = client.images.generate(
    model="qwen-image",
    prompt="منظره آرام کوهستانی با دریاچه شفاف که قله‌های برفی را منعکس می‌کند",
    size="1328x1328",  # پشتیبانی از نسبت‌های مختلف ابعاد
    n=1,
    response_format="url",  # or b64_json
)

print(f"URL تصویر تولید شده: {response.data[0].url}")

# ویرایش تصویر
import requests

with open("input_image.jpg", "rb") as image_file:
    edit_response = requests.post(
        "https://api.avalai.ir/v1/images/edits",
        headers={"Authorization": f"Bearer {os.environ['AVALAI_API_KEY']}"},
        files={"image": image_file},
        data={
            "model": "qwen-image-edit",
            "prompt": "آسمان را به غروب دراماتیک با رنگ‌های نارنجی و بنفش تغییر دهید",
        },
    )

print(f"تصویر ویرایش شده: {edit_response.json()}")

استفاده از فرمت بومی Dashscope

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

# مثال پایتون با استفاده از فرمت بومی Dashscope برای ویژگی‌های پیشرفته
import os
import requests

# تولید متن-به-تصویر پیشرفته با پارامترهای بومی Dashscope
response = requests.post(
    "https://api.avalai.ir/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['AVALAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": [
                        {
                            "text": "عکس پرتره حرفه‌ای از یک فرد تجاری مطمئن در محیط اداری مدرن"
                        }
                    ],
                }
            ]
        },
        "parameters": {
            "size": "1328*1328",  # نکته: Dashscope از * به جای x استفاده می‌کند
            "prompt_extend": True,  # فعال‌سازی بهبود هوشمند prompt
            "watermark": False,  # کنترل watermark
            "negative_prompt": "تار، کیفیت پایین، تحریف شده، غیرحرفه‌ای",
            "seed": 12345,  # برای نتایج قابل تکرار
        },
    },
)

print(f"نتیجه تولید پیشرفته: {response.json()}")

# ویرایش پیشرفته تصویر با چندین تصویر
edit_response = requests.post(
    "https://api.avalai.ir/v1/images/edits",
    headers={
        "Authorization": f"Bearer {os.environ['AVALAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-edit",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": [
                        {
                            "image": "https://example.com/input-image.jpg"  # یا داده base64
                        },
                        {
                            "text": "فرد را به حالت ایستاده تغییر دهید که خم شده و پنجه‌های جلویی سگ را گرفته است"
                        },
                    ],
                }
            ]
        },
        "parameters": {
            "negative_prompt": "تحریف شده، ژست غیرطبیعی",
            "watermark": False,
        },
    },
)

print(f"نتیجه ویرایش پیشرفته: {edit_response.json()}")

ویژگی‌های اختصاصی مدل Qwen

• نسبت‌های مختلف ابعاد: 1:1، 4:3، 3:4، 16:9، 9:16 (1328×1328، 1664×928، 1472×1140، 1140×1472، 928×1664)
• بهبود هوشمند Prompt: بازنویسی خودکار prompt برای نتایج بهتر
• Promptهای منفی: مشخص کردن آنچه که نمی‌خواهید در تصویر باشد
• کنترل Watermark: انتخاب اضافه کردن یا نکردن watermark Qwen-Image
• پشتیبانی Seed: نتایج قابل تکرار با مقادیر seed ثابت
• ورودی چند تصویری: پشتیبانی از چندین تصویر مرجع در وظایف ویرایش

نکته مهم برای مدل‌های Qwen: در حالی که مدل‌های Qwen از promptهای چینی و انگلیسی پشتیبانی می‌کنند، استفاده از promptهای انگلیسی واضح و توصیفی اغلب بهترین نتایج را برای موارد استفاده بین‌المللی به همراه دارد.

تولیدات (Generations)

با استفاده از نقطه پایانی v1/images/generations یک تصویر اصلی از یک پرامپت متنی ایجاد کنید.

Python

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

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

try:
    response = client.images.generate(
        model="gpt-image-2",
        prompt="یک گربه سیامی سفید در استودیوی مینیمال با نور آفتاب",
        size="1024x1024",
        quality="medium",
        n=1,
    )
    image_base64 = response.data[0].b64_json
    with open("siamese-cat.png", "wb") as image_file:
        image_file.write(base64.b64decode(image_base64))
    print("Saved siamese-cat.png")
except Exception as e:
    print(f"An error occurred: {e}")

JavaScript

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

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

async function main() {
  try {
    const response = await client.images.generate({
      model: "gpt-image-2",
      prompt: "یک گربه سیامی سفید در استودیوی مینیمال با نور آفتاب",
      n: 1,
      size: "1024x1024",
      quality: "medium",
    });

    const imageBase64 = response.data[0].b64_json;
    fs.writeFileSync("siamese-cat.png", Buffer.from(imageBase64, "base64"));
    console.log("Saved siamese-cat.png");
  } catch (error) {
    if (error.response) {
      console.error(error.response.status, error.response.data);
    } else {
      console.error(`Error with AvalAI API request: ${error.message}`);
    }
  }
}
main();

Bash

# مثال cURL با استفاده از AvalAI برای تولید تصویر
curl https://api.avalai.ir/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "یک گربه سیامی سفید در استودیوی مینیمال با نور آفتاب",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium"
}' | jq -r '.data[0].b64_json' | base64 --decode >siamese-cat.png

گزینه‌های اندازه و کیفیت

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

• GPT Image 2: اندازه‌های استاندارد مانند 1024x1024، 1536x1024 و 1024x1536 را پشتیبانی می‌کند و در routeهای سازگار می‌تواند resolution سفارشی را هم بپذیرد، به شرطی که هر دو بعد با محدودیت‌های ارائه‌دهنده سازگار باشند. برای draft از quality: "low"، برای بیشتر previewهای production از medium، برای جزئیات نهایی از high و برای انتخاب خودکار از auto استفاده کنید.
• چک‌لیست اندازه سفارشی GPT Image 2: بلندترین ضلع را حداکثر 3840px نگه دارید، هر دو بعد باید مضرب 16px باشند، نسبت ضلع بلند به ضلع کوتاه از 3:1 بیشتر نشود و مجموع پیکسل‌ها بین 655,360 و 8,294,400 باشد. خروجی‌های بزرگ‌تر از 2560x1440 را تا زمان تست latency، هزینه و ثبات بصری روی route AvalAI خود، experimental در نظر بگیرید.
• فرمت خروجی: routeهای GPT Image داده تصویر را به‌صورت Base64 برمی‌گردانند. وقتی route انتخابی سفارشی‌سازی خروجی را پشتیبانی کند، output_format را به png، jpeg یا webp تنظیم کنید؛ برای کنترل حجم JPEG/WebP از output_compression استفاده کنید.
• پس‌زمینه: پس‌زمینه شفاف به فرمتی با alpha مانند PNG یا WebP و پشتیبانی مدل نیاز دارد. مرجع فعلی OpenAI برای gpt-image-2 پس‌زمینه شفاف را پشتیبانی‌شده نمی‌داند؛ بنابراین تا وقتی route شما پشتیبانی را تأیید نکرده، background: "auto" یا opaque را نگه دارید.
• Input fidelity: برای gpt-image-2 پارامتر input_fidelity را ارسال نکنید؛ راهنمای فعلی OpenAI می‌گوید این مدل همه ورودی‌های تصویری را خودکار با fidelity بالا پردازش می‌کند. در routeهای قدیمی‌تر GPT Image که input_fidelity را ارائه می‌کنند، برای چهره‌ها، لوگوها، packaging، screenshotهای UI یا ویرایش‌هایی که حفظ جزئیات مهم است از high استفاده کنید.

پرامپت‌نویسی

پرامپت‌های واضح و توصیفی ارائه دهید. routeهای GPT Image و ابزار تصویر Responses ممکن است پرامپت‌ها را برای جزئیات یا ایمنی بازبینی کنند. پرامپت بازبینی شده ممکن است در شی پاسخ (فیلد revised_prompt) در صورت پشتیبانی توسط ادغام AvalAI در دسترس باشد.

هنگام استفاده از ابزار تولید تصویر در Responses API، در صورت وجود image_generation_call.revised_prompt آن را بررسی کنید. این فیلد برای debugging بازنویسی پرامپت و توضیح اینکه چرا دو پرامپت مشابه خروجی متفاوت داده‌اند مفید است.

Streaming و تصویرهای جزئی

برخی routeهای GPT Image می‌توانند هنگام رندر نهایی، تصویرهای جزئی را stream کنند. اگر route شما stream و partial_images را پشتیبانی می‌کند، برای preview تعاملی 1 تا 3 تصویر جزئی درخواست کنید و همچنان تصویر نهایی را از پاسخ completed ذخیره کنید. تصویرهای جزئی را preview تدریجی بدانید، نه asset نهایی. اگر render نهایی سریع کامل شود ممکن است تعداد تصویر جزئی دریافتی کمتر از مقدار درخواستی باشد، و previewهای جزئی می‌توانند روی مصرف token یا هزینه تصویر اثر بگذارند؛ پیش از فعال‌سازی پیش‌فرض، قیمت route AvalAI را بررسی کنید.

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

به مدل و routeی نیاز دارد که ویرایش را پشتیبانی کند؛ مانند routeهای GPT Image یا مدل‌های ویرایش اختصاصی ارائه‌دهندگان که در AvalAI فعال شده‌اند.

نقطه پایانی v1/images/edits امکان اصلاح بخش‌هایی از یک تصویر را با استفاده از ماسک فراهم می‌کند. تصویر اصلی و ماسکی با ابعاد یکسان را آپلود کنید؛ در workflowهای GPT Image مبتنی بر ماسک، ماسک باید alpha channel داشته باشد. پرامپت باید کل تصویر نهایی مورد نظر را توصیف کند، نه فقط ناحیه تغییر.

import base64
import os
from openai import OpenAI

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

try:
    response = client.images.edit(
        model="gpt-image-2",
        image=open("original_image.png", "rb"),
        mask=open("mask.png", "rb"),
        prompt="یک سالن استراحت داخلی آفتاب‌گیر با استخری پر از فلامینگو",
        n=1,
        size="1024x1024",
    )
    image_base64 = response.data[0].b64_json
    with open("edited-lounge.png", "wb") as image_file:
        image_file.write(base64.b64decode(image_base64))
except Exception as e:
    print(f"An error occurred: {e}")
    # بررسی کنید که آیا مدل از ویرایش پشتیبانی می‌کند یا فرمت‌های تصویر/ماسک صحیح هستند

ارسال تصویر Base64 به Edits بدون SDK

برای محیط‌های بدون SDK، v1/images/edits را مستقیم صدا بزنید. در درخواست‌های JSON سبک GPT Image، هر تصویر منبع را در آرایه images قرار دهید و Base64 data URL را از طریق image_url ارسال کنید. این با schema مورد انتظار OpenAI برای editهای JSON هم‌خوان است: هر object تصویر باید دقیقا یکی از image_url یا file_id را داشته باشد، و image_url می‌تواند URL کامل یا data URL با Base64 باشد.

Bash

# در macOS/BSD از `-i` استفاده می‌شود؛ در Linux می‌توانید `base64 -w 0 input_image.png` را به‌کار ببرید
IMAGE_BASE64=$(base64 -i input_image.png | tr -d '\n')

curl https://api.avalai.ir/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "فقط پس‌زمینه را به ساحل گرمسیری تغییر بده و شخص، ژست و نورپردازی را حفظ کن",
  "images": [
    {
      "image_url": "data:image/png;base64,'"$IMAGE_BASE64"'"
    }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "n": 1
}' | jq -r '
  .data[0]
  | if .b64_json then .b64_json
    elif (.url // "" | startswith("data:")) then (.url | split(",")[1])
    else error("response did not include b64_json or a data URL")
    end
' | base64 --decode >edited-beach.png

Python

import base64
import os

import requests


def save_image_result(image, output_path):
    """Save an image result that may contain b64_json, a data URL, or a URL."""
    if image.get("b64_json"):
        image_bytes = base64.b64decode(image["b64_json"])
    elif image.get("url", "").startswith("data:"):
        _, encoded = image["url"].split(",", 1)
        image_bytes = base64.b64decode(encoded)
    elif image.get("url"):
        image_response = requests.get(image["url"], timeout=120)
        image_response.raise_for_status()
        image_bytes = image_response.content
    else:
        raise ValueError(f"No image payload found in response item: {image}")

    with open(output_path, "wb") as image_file:
        image_file.write(image_bytes)


with open("input_image.png", "rb") as image_file:
    image_base64 = base64.b64encode(image_file.read()).decode("utf-8")

response = requests.post(
    "https://api.avalai.ir/v1/images/edits",
    headers={
        "Authorization": f"Bearer {os.environ['AVALAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": (
            "فقط پس‌زمینه را به ساحل گرمسیری تغییر بده و شخص، ژست "
            "و نورپردازی را حفظ کن"
        ),
        "images": [{"image_url": f"data:image/png;base64,{image_base64}"}],
        "size": "1024x1024",
        "quality": "medium",
        "n": 1,
    },
    timeout=120,
)
response.raise_for_status()

save_image_result(response.json()["data"][0], "edited-beach.png")

وقتی route فایل uploadشده یا ماسک binary می‌خواهد، به‌جای JSON از multipart/form-data استفاده کنید. در این حالت با curl مقدارهای image=@input_image.png و mask=@mask.png را بفرستید، یا در Python requests از files={"image": image_file, "mask": mask_file} استفاده کنید. برای mask در JSON هم object مشابه تصویر بفرستید، مثلا { "image_url": "data:image/png;base64,..." } یا { "file_id": "file_..." }.

الزامات:

• تصویر و ماسک باید ابعاد یکسان و فرمت‌های سازگار داشته باشند. فایل‌ها را زیر محدودیت upload route انتخابی نگه دارید؛ مرجع GPT Image در OpenAI برای editها راهنمای کمتر از 50 مگابایت برای تصویر/ماسک دارد.
• وقتی route از transparency برای تعیین ناحیه قابل ویرایش استفاده می‌کند، ماسک باید alpha channel داشته باشد.
• در workflowهای دارای چند تصویر مرجع، هر تصویر مرجع را صریح ارسال کنید و اثر توکن/هزینه را پیش از production تست کنید. برای تکنیک‌های ماسک‌گذاری به تولید تصویر با مدل‌های GPT Image مراجعه کنید.

تغییرات (وابسته به مدل)

هشدار

ویژگی پیاده‌سازی نشده!

این قابلیت در حال حاضر در حال توسعه است و هنوز در AvalAI در دسترس نیست. ما انتشار آن را از طریق کانال‌های رسمی خود اعلام خواهیم کرد. منتظر به‌روزرسانی‌های ما باشید!

AvalAI در حال حاضر مدل variation پشتیبانی‌شده‌ای را در data/models.json فهرست نمی‌کند. فعلا variation را با v1/images/generations و brief دقیق از تصویر منبع، یا با v1/images/edits و تصویر منبع به‌عنوان reference پیاده‌سازی کنید.

نظارت محتوا

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

برای routeهای GPT Image که کنترل moderation در سبک OpenAI را ارائه می‌کنند، در production مقدار moderation: "auto" را نگه دارید. فقط پس از review محصول و ایمنی از moderation: "low" استفاده کنید، چون در مدل‌های پشتیبانی‌شده می‌تواند فیلترینگ را کمتر سخت‌گیرانه کند.

وقتی درخواست block می‌شود، همان payload را کورکورانه retry نکنید. request ID، endpoint، مدل و error code پایدار را log کنید؛ اگر ارائه‌دهنده moderation details برگرداند، آن را در log توسعه‌دهنده نگه دارید و به کاربر پیام عمومی مثل «پرامپت یا تصویر ورودی را اصلاح کنید و دوباره تلاش کنید» نشان دهید. جزئیات سبک OpenAI ممکن است شامل moderation_stage (input، output یا unknown) و categories کلی مثل harassment، self-harm، sexual یا violence باشد؛ این فیلدها را hint اختیاری برای debugging بدانید، نه توضیح classifier برای کاربر نهایی.

خطاهای مخصوص تصویر را از خطاهای موقت زیرساخت جدا مدیریت کنید. اگر ارائه‌دهنده کد سبک OpenAI یعنی image_generation_user_error برگرداند، پیش از retry باید prompt، تصویر آپلودشده، mask، اندازه یا گزینه پشتیبانی‌نشده را تغییر دهید. اگر کد moderation_blocked بود، ابتدا بر اساس همین کد پایدار branch کنید و سپس از moderation_details اختیاری فقط برای انتخاب hint امن‌تر برای کاربر استفاده کنید.

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

مثال‌ها خواندن فایل‌ها از دیسک را نشان می‌دهند. همچنین می‌توانید از داده‌های تصویر در حافظه استفاده کنید (به عنوان مثال BytesIO در پایتون، Buffer در Node.js). اطمینان حاصل کنید که شی داده شامل نام فایلی با پسوند صحیح (مانند .png) هنگام ارسال آن به تابع SDK باشد.

# مثال پایتون با داده‌های درون حافظه (BytesIO)
import os
from io import BytesIO
from PIL import Image  # مثال با استفاده از کتابخانه Pillow
from openai import OpenAI

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

# فرض کنید 'image_data' بایت‌های خام تصویر شما است (مثلا از یک دانلود)
# image = Image.open(BytesIO(image_data)) # مثال: بارگیری بایت‌ها در Pillow

# # --- پردازش اختیاری تصویر (مثلا تغییر اندازه) ---
# width, height = 512, 512
# image = image.resize((width, height))
# # --- پایان پردازش اختیاری ---

byte_stream = BytesIO()
# ذخیره در شی BytesIO، اطمینان از فرمت PNG در صورت نیاز توسط نقطه پایانی API
image.save(byte_stream, format="PNG")
byte_array = byte_stream.getvalue()

try:
    byte_stream.name = "reference.png"
    response = client.images.edit(
        model="gpt-image-2",
        image=byte_stream,
        prompt="ترکیب‌بندی اصلی را حفظ کن اما نورپردازی را گرم‌تر کن.",
        n=1,
        size="1024x1024",
    )
    print(response.data[0].b64_json[:80] + "...")
except Exception as e:
    print(f"An error occurred: {e}")

مثال با مدل FLUX

در اینجا یک مثال کامل از تولید تصویر با استفاده از یک مدل پشتیبانی‌شده Black Forest Labs آمده است:

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

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

try:
    response = client.images.generate(
        model="flux.2-pro",
        prompt="A photorealistic mountain landscape with a lake reflecting the sunset, detailed lighting, high resolution",
        size="1024x1024",
        extra_body={
            "aspect_ratio": "16:9",
            "output_format": "png",
            "safety_tolerance": 2,
            "prompt_upsampling": True,
        },
        response_format="url",
    )
    image_url = response.data[0].url
    print(f"Generated image URL: {image_url}")
except Exception as e:
    print(f"An error occurred: {e}")

مدیریت خطا

فراخوانی‌های API را در بلوک‌های try...except (پایتون) یا try...catch (جاوااسکریپت) قرار دهید تا خطاهای احتمالی مانند ورودی‌های نامعتبر، محدودیت‌های نرخ یا مشکلات ارائه دهنده را مدیریت کنید.

# مثال مدیریت خطای پایتون
import os
import openai
from openai import OpenAI

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

try:
    response = client.images.generate(
        model="gpt-image-2",
        prompt="یک پرامپت معتبر",
        n=1,
        size="1024x1024",
    )
    print(response.data[0].b64_json[:80] + "...")
except openai.APIError as e:
    # خطاهای API را مدیریت می‌کند (مانند محدودیت‌های نرخ، خطاهای سرور از AvalAI/ارائه دهنده)
    print(f"API Error: {e.status_code} - {e.message}")
    print(e.body)  # شامل جزئیات بیشتر است
except openai.AuthenticationError as e:
    print(f"Authentication Error: {e.message}")
except openai.BadRequestError as e:
    print(f"Bad Request Error: {e.message}")  # به عنوان مثال پارامترهای نامعتبر
except Exception as e:
    # خطاهای احتمالی دیگر را مدیریت می‌کند (مشکلات شبکه و غیره)
    print(f"An unexpected error occurred: {e}")