Image Generation

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

POST /v1/images/generations

اطلاع

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

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

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

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

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

شروع سریع

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:gpt-image-1",
  "prompt": "یک تصویر مینیمال از داشبورد هوش مصنوعی سازمانی با رنگ‌های آرام و فضای حرفه‌ای",
  "size": "1024x1024",
  "quality": "medium",
  "n": 1
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-image-1",
  "prompt": "یک تصویر مینیمال از داشبورد هوش مصنوعی سازمانی با رنگ‌های آرام و فضای حرفه‌ای",
  "size": "1024x1024",
  "quality": "medium",
  "n": 1
}),
});

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

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

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/images/generations" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:gpt-image-1",
  "prompt": "یک تصویر مینیمال از داشبورد هوش مصنوعی سازمانی با رنگ‌های آرام و فضای حرفه‌ای",
  "size": "1024x1024",
  "quality": "medium",
  "n": 1
}'

OpenAI Python SDK

from openai import OpenAI

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

response = client.images.generate(
    "model": "openai:default:gpt-image-1",
    prompt="یک تصویر مینیمال از داشبورد هوش مصنوعی سازمانی با رنگ‌های آرام و فضای حرفه‌ای",
    size="1024x1024",
    quality="medium",
    n=1

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

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

const response = await client.images.generate({
  "model": "openai:default:gpt-image-1",
  "prompt": "یک تصویر مینیمال از داشبورد هوش مصنوعی سازمانی با رنگ‌های آرام و فضای حرفه‌ای",
  "size": "1024x1024",
  "quality": "medium",
  "n": 1
});

console.log(response);

نکته

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

پیش‌نیازها

• نشانی پایه درگاه، مانند https://YOUR_WORKSPACE.godarai.ir/v1.
• توکن معتبر گدارAI.
• مدلی از نوع image_generation که در فضای کاری شما مجاز باشد.
• بودجه و سقف نرخ کافی برای درخواست‌های تصویری.

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

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

حداقل درخواست:

{
  "model": "openai:default:gpt-image-1",
  "prompt": "یک تصویر واقع‌گرایانه از تیم پشتیبانی در حال کار با داشبورد هوش مصنوعی"
}

پارامترهای رایج:

پارامتر	کاربرد
prompt	توضیح متنی تصویر مورد نظر.
n	تعداد تصویرهای خروجی.
size	اندازه تصویر، مثل 1024x1024.
quality	سطح کیفیت، اگر مدل پشتیبانی کند.
response_format	فرمت خروجی در مدل‌هایی که از آن پشتیبانی می‌کنند؛ برای مدل‌های قدیمی‌تر معمولاً url یا b64_json.
output_format	فرمت فایل خروجی در مدل‌های GPT Image، مثل png، jpeg یا webp.
output_compression	فشرده‌سازی خروجی برای jpeg یا webp، اگر مدل پشتیبانی کند.
moderation	سطح پالایش محتوای تصویر در مدل‌هایی که این فیلد را می‌پذیرند.

هشدار

پشتیبانی دقیق size، quality، response_format، output_format و moderation به مدل و ارائه‌دهنده انتخابی بستگی دارد. مدل‌های GPT Image معمولاً داده تصویر را در b64_json برمی‌گردانند؛ URL خروجی برای همه مدل‌ها در دسترس نیست.

خروجی

پاسخ در مدل‌های GPT Image معمولاً داده base64 برمی‌گرداند:

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

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

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

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

import base64

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

پرامپت خوب برای تصویر

پرامپت تصویری خوب معمولاً این اجزا را دارد:

• موضوع اصلی تصویر.
• سبک یا فضای بصری.
• محدودیت‌های مهم؛ مثل «بدون متن روی تصویر».
• نسبت یا اندازه مورد انتظار، اگر مدل پشتیبانی کند.
• کاربرد نهایی تصویر؛ مثل بنر، آیکن، تصویر مقاله یا نمونه محصول.

نمونه بهتر:

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

هزینه و پایش

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

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

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

حریم خصوصی

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

خطاهای رایج

نشانه	علت محتمل	راه‌حل
model is required	فیلد model ارسال نشده است.	شناسه مدل مجاز یا مدل مجازی را وارد کنید.
prompt is required	فیلد prompt خالی است یا ارسال نشده است.	توضیح متنی تصویر را در prompt بفرستید.
Model access denied or unsupported for image generation	مدل برای تصویر مجاز نیست.	مدل نوع image_generation انتخاب کنید.
No available deployment for model: ...	مقصد فعالی برای مدل پیدا نشده است.	تنظیمات مدل مجازی یا حساب ارائه‌دهنده را بررسی کنید.
خطای ارائه‌دهنده درباره size یا quality	پارامتر با مدل سازگار نیست.	مقدار پارامتر را با مدل فعال هماهنگ کنید.

جمع‌بندی

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