Generate an image

یک یا چند تصویر از روی متن توصیفی (و اختیاری تصویر مرجع) با مدل انتخابی تولید می‌کند.

نقطهٔ پایانی POST /images/generations به‌ازای هر درخواست، تصویر را به‌صورت بیس‌۶۴ (Base64) برمی‌گرداند. خروجی و پارامترها مطابق فرمت استاندارد OpenAI است، با گزینه‌های پیشرفتهٔ آشا برای نسبت تصویر، کیفیت و فرمت.

Endpoint

                POST
                /images/generations
              

https://app.asha-ai.ir/v1/images/generations

احراز هویت

با کلید API آشا از طریق هدر Authorization: Bearer <ASHA_API_KEY> احراز هویت کنید.

پارامترهای بدنهٔ درخواست

پارامتر	نوع	پیش‌فرض	توضیح
`model`	string	—	الزامی. شناسهٔ مدل تولید تصویر، مانند `openai/gpt-image-1`.
`prompt`	string	—	الزامی. متن توصیفی که تصویر بر اساس آن ساخته می‌شود.
`id`	string	—	خطای اختیاری برای ردیابی و جلوگیری از درخواست‌های تکراری.
`seed`	integer	تصادفی	دانهٔ تولید برای بازتولید همان تصویر.
`n`	integer	`1`	تعداد تصاویر خروجی (بین ۱ تا ۱۰).
`size`	string	طبق مدل	اندازهٔ تصویر؛ یا رستهٔ مدل مانند `"2K"` یا ابعاد پیکسلی مانند `"2048x2048"`.
`aspect_ratio`	enum	`auto`	نسبت تصویر؛ `auto`، `1:1`، `16:9`، `9:16`، `4:3`، `3:4` و موارد دیگر.
`quality`	enum	`auto`	کیفیت؛ `auto`، `low`، `medium`، `high`.
`resolution`	enum	طبق مدل	رزولوشن؛ `512`، `1K`، `2K`، `4K`.
`output_format`	enum	`png`	فرمت خروجی؛ `png`، `jpeg`، `webp`، `svg`.
`output_compression`	integer	—	میزان فشرده‌سازی خروجی بین ۰ تا ۱۰۰.
`background`	enum	`auto`	پس‌زمینه؛ `auto`، `transparent`، `opaque`.
`input_references`	array	—	لیست تصاویر مرجع برای ویرایش یا الهام؛ حداکثر ۱۶ مورد.
`provider`	object	—	ترجیحات مسیریابی (پروایدر و درجهٔ حذف) مطابق سیاست آشا.

مثال درخواست

curl https://app.asha-ai.ir/v1/images/generations 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "a cute baby sea otter",
    "n": 1,
    "quality": "high"
  }'

import requests

response = requests.post(
    'https://app.asha-ai.ir/v1/images/generations',
    headers={'Authorization': 'Bearer <ASHA_API_KEY>'},
    json={
        'model': 'openai/gpt-image-1',
        'prompt': 'a cute baby sea otter',
        'n': 1,
        'quality': 'high',
    },
)

data = response.json()
for image in data['data']:
    print(f"created={data['created']} bytes={len(image['b64_json'])}")

const response = await fetch('https://app.asha-ai.ir/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ASHA_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-image-1',
    prompt: 'a cute baby sea otter',
    n: 1,
    quality: 'high',
  }),
});

const data = await response.json();
for (const image of data.data) {
  console.log(`created=${data.created} bytes=${image.b64_json.length}`);
}

پاسخ موفق

در صورت موفقیت، پاسخ با کد 200 برمی‌گردد:

                JSON
                200 OK
              

{
  "created": 1728842345,
  "data": [
    {
      "b64_json": "…base64-encoded image…",
      "media_type": "image/png"
    }
  ],
  "usage": {
    "prompt_tokens": 84,
    "completion_tokens": 900,
    "total_tokens": 984,
    "cost": 0.0042
  }
}

خطاها

کد	توضیح
`400`	درخواست ناقص یا پارامتر نامعتبر (مثلاً بیشتر از ۱۰ تصویر).
`401`	هدر احراز هویت وجود ندارد یا کلید نامعتبر است.
`402`	موجودی حساب برای انجام درخواست کافی نیست.
`403`	دسترسی به مدل یا منبع برای شما مجاز نیست.
`404`	مدل درخواستی یافت نشد.
`413`	درخواست بیش از حد بزرگ است (مثلاً تعداد مراجع زیاد).
`429`	نرخ درخواست از سقف مجاز عبور کرده است.
`500`	خطای داخلی سرور.
`502`	پروایدر بالادستی پاسخ نامعتبر برگردانده است.
`524`	مهلت پردازش پروایدر به پایان رسیده است.
`529`	سرویس شلوغ است؛ کمی بعد دوباره تلاش کنید.