تولید تصویر — Image generation

کشف مدل‌ها

مدل‌های تولید تصویر از طریق endpoint سازگار با OpenAI یعنی GET /v1/models در دسترس‌اند. هر مدل فیلد architecture.output_modalities دارد که حالت‌های خروجیِ پشتیبانی‌شده (مثل image) را فهرست می‌کند:

curl "https://app.asha-ai.ir/v1/models"

مدل‌هایی که "image" را در architecture.output_modalities دارند، مدل‌های تولید تصویرند. فهرست کامل و قیمت به تومان در صفحهٔ مدل‌ها هم نمایش داده می‌شود.

استفاده از API

درخواست POST به /v1/images/generations با مدل و prompt بفرستید:

import os

import requests

url = "https://app.asha-ai.ir/v1/images/generations"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

payload = {
    "model": "~bytedance-seed/seedream-4.5",
    "prompt": "a red panda astronaut floating in space, studio lighting",
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

for image in result["data"]:
    # image["b64_json"] contains the base64-encoded image
    print(f"Generated image ({len(image['b64_json'])} chars)")

package main

import (
	"bytes"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	payload := map[string]any{
		"model":  "~bytedance-seed/seedream-4.5",
		"prompt": "a red panda astronaut floating in space, studio lighting",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://app.asha-ai.ir/v1/images/generations", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ASHA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result struct {
		Data []struct {
			B64JSON string `json:"b64_json"`
		} `json:"data"`
	}
	_ = json.NewDecoder(resp.Body).Decode(&result)

	for _, image := range result.Data {
		raw, _ := base64.StdEncoding.DecodeString(image.B64JSON)
		fmt.Printf("Generated image (%d bytes)n", len(raw))
	}
}

const response = await fetch("https://app.asha-ai.ir/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "~bytedance-seed/seedream-4.5",
    prompt: "a red panda astronaut floating in space, studio lighting",
  }),
});

const result = await response.json();

for (const image of result.data) {
  // image.b64_json contains the base64-encoded image
  console.log(`Generated image (${image.b64_json.length} chars)`);
}

const response = await fetch("https://app.asha-ai.ir/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "~bytedance-seed/seedream-4.5",
    prompt: "a red panda astronaut floating in space, studio lighting",
  }),
});

const result = await response.json();

for (const image of result.data) {
  // image.b64_json contains the base64-encoded image
  console.log(`Generated image (${image.b64_json.length} chars)`);
}

curl -X POST "https://app.asha-ai.ir/v1/images/generations" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "~bytedance-seed/seedream-4.5",
    "prompt": "a red panda astronaut floating in space, studio lighting"
  }'

قالب پاسخ

خروجی‌ها به‌صورت بایت‌های base64 برگردانده می‌شوند. فیلد usage تعداد توکن‌ها و هزینه را — هر وقت در دسترس بود — گزارش می‌دهد. فیلد media_type وقتی حاضر است که فرمت قابل شناسایی باشد (از جمله image/png) و فقط وقتی حذف می‌شود که نتوان آن را تعیین کرد:

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>",
      "media_type": "image/png"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4175,
    "total_tokens": 4175,
    "cost": 750
  }
}

برای خروجی‌های غیر-PNG (مثل JPEG، WebP یا SVG در مدل‌های وکتوری Recraft)، media_type فرمت واقعی را نشان می‌دهد:

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>",
      "media_type": "image/svg+xml"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4175,
    "total_tokens": 4175,
    "cost": 750
  }
}

گزینه‌های پیکربندی تصویر

رزولوشن و نسبت تصویر

ابعاد خروجی را با resolution، aspect_ratio یا میان‌برِ راحت‌ترِ size کنترل کنید:

{
  "model": "~bytedance-seed/seedream-4.5",
  "prompt": "a landscape photo",
  "resolution": "2K",
  "aspect_ratio": "16:9"
}

• resolution — سطح نرمال‌شده (512، 1K، 2K، 4K)؛ پیکسل‌های دقیق بسته به ارائه‌دهنده استخراج می‌شوند.
• aspect_ratio — نسبت نرمال‌شده؛ auto یعنی خودِ ارائه‌دهنده انتخاب کند. مقادیر رایج: 1:1، 16:9، 9:16، 4:3، 3:4، 3:2، 2:3، 4:5، 5:4 و نسبت‌های کشیده مانند 1:2، 2:1، 1:4، 4:1، 1:8، 8:1، 9:21، 21:9. ارائه‌دهنده به زیرمجموعهٔ پشتیبانی‌شدهٔ خودش مقیاس می‌دهد.
• size — میان‌بر؛ یک سطح ("2K") یا پیکسل صریح ("2048x2048") بدهید تا برای ارائه‌دهنده نرمال شود. سطح، معادل تنظیم resolution است و با aspect_ratio ترکیب می‌شود. پیکسل صریح، مرجعِ حاکم است و همراهیِ resolution/aspect_ratio نامتناسب با آن، خطای 400 می‌دهد.

بسته به مدل، فقط برخی از این گزینه‌ها پشتیبانی می‌شوند؛ گزینه‌های ناپشتیبانی نادیده گرفته می‌شوند یا خطای 400 می‌دهند.

کیفیت و فرمت خروجی

{
  "model": "~openai/gpt-image-1",
  "prompt": "a product photo",
  "quality": "high",
  "output_format": "png",
  "background": "transparent"
}

• quality — auto، low، medium یا high. ارائه‌دهنده‌های بدون دستگیرهٔ کیفیت، آن را نادیده می‌گیرند.
• output_format — png، jpeg، webp یا svg (فقط مدل‌های وکتوری‌سازی؛ مارک‌آپ SVG داخل b64_json کد می‌شود).
• background — auto، transparent یا opaque. transparent به فرمتِ دارای آلفا (png یا webp) نیاز دارد.
• output_compression — 0 تا 100 برای webp/jpeg؛ برای png نادیده گرفته می‌شود.

چند تصویر

با n تا ۱۰ تصویر در یک درخواست بخواهید:

{
  "model": "~openai/gpt-image-1",
  "prompt": "a cute cat",
  "n": 4
}

همهٔ ارائه‌دهنده‌ها از n > 1 پشتیبانی نمی‌کنند؛ در صورت نبود پشتیبانی، خطای 400 برمی‌گردد.

تبدیل تصویر به تصویر (تصویر مرجع)

تصویر مرجع را با input_references بفرستید تا ساخت‌وساز را هدایت کند:

{
  "model": "~openai/gpt-image-1",
  "prompt": "make this scene look like a watercolor painting",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg"
      }
    }
  ]
}

تصویر مرجع می‌تواند URL (HTTP/S) یا Data URL base64 باشد. تعداد مراجع پذیرفته‌شده بسته به ارائه‌دهنده متفاوت است.

مسیریابی انتخاب ارائه‌دهنده

وقتی مدلی چند ارائه‌دهنده دارد، با شیءِ provider مشخص کنید کدام endpointها می‌توانند درخواست را پاسخ بدهند:

{
  "model": "~google/gemini-2.5-flash-image",
  "prompt": "a red panda astronaut floating in space",
  "provider": {
    "only": ["google-ai-studio"],
    "allow_fallbacks": false
  }
}

Image API این فیلدهای مسیریابی را پشتیبانی می‌کند:

• only — فقط ارائه‌دهنده‌های لیست‌شده.
• order — ارائه‌دهنده‌ها را به همین ترتیب امتحان کن.
• ignore — ارائه‌دهنده‌های لیست‌شده را کنار بگذار.
• sort — endpointهای واجدشرایط را بر اساس price، throughput یا latency مرتب کن.
• allow_fallbacks — وقتی false باشد، پس از ارائه‌دهندهٔ اصلی متوقف شود.

گزینه‌های مختص ارائه‌دهنده

پارامترهای مشخصِ هر ارائه‌دهنده را از طریق provider.options — با کلیدِ ارائه‌دهنده از endpoint API — بفرستید:

{
  "model": "~black-forest-labs/flux.2-pro",
  "prompt": "a dramatic portrait",
  "provider": {
    "options": {
      "black-forest-labs": {
        "steps": 40,
        "guidance": 3
      }
    }
  }
}

فیلد provider.options با کلیدِ نام ارائه‌دهنده، پارامترهای مختص همان ارائه‌دهنده را منتقل می‌کند.

صورت‌حساب و لغو

صورت‌حساب تولید تصویر همه یا هیچ است: یا تولید کامل می‌شود و کل مبلغ کسر می‌شود، یا شکست می‌خورد و مبلغی کسر نمی‌شود. این با chat completions فرق دارد، جایی که جریانِ لغوشده، برای توکن‌های تولیدشدهٔ پیش از لغو حساب می‌شود.

• تولیدهای تکمیل‌شده بر اساس قیمت‌گذاری endpoint، برای کل خروجی تصویر صورت‌حساب می‌شوند.
• تولیدهای شکست‌خورده یا لغوشده صورت‌حساب نمی‌شوند. وقتی تولید کامل نشود، درخواست با 502 Bad Gateway برمی‌گردد و هیچ هزینه‌ای ثبت نمی‌شود.

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

پارامترهای درخواست

برای اینکه بدانید هر مدل کدام پارامترها را پشتیبانی می‌کند، دادهٔ مدل را در GET /v1/models ببینید.

سؤالات متداول