تولید تصویر

با endpoint تولید تصویر می‌توانید از روی یک توضیح متنی (prompt) تصویر بسازید. این endpoint با images.generate در SDKهای OpenAI سازگار است.

POST https://hooshvana.ir/api/v1/images/generations

پارامترها

اندازه‌ها

اندازه‌ها و قابلیت‌های دقیق هر مدل در کاتالوگ مدل‌ها آمده است. اندازه‌ی نامعتبر با خطای invalid_request رد می‌شود.

درخواست با cURL

curl https://hooshvana.ir/api/v1/images/generations \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A cozy Persian tea house at sunset, warm light, watercolor style",
    "size": "1024x1024",
    "n": 1
  }'

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

{
  "created": 1792000000,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }]
}

{
  "created": 1792000000,
  "data": [{ "url": "https://...", "revised_prompt": "..." }]
}

آدرس‌های url موقت‌اند و بعد از مدتی از کار می‌افتند. اگر تصویر را لازم دارید، آن را دانلود و در فضای ذخیره‌سازی خودتان نگه دارید.

ذخیره‌ی خروجی در فایل با Python

import base64
import os
import urllib.request
from openai import OpenAI

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

result = client.images.generate(
    model="openai/gpt-image-2",
    prompt="Minimal flat illustration of a smartphone showing a Persian chat app",
    size="1024x1536",
)

for i, image in enumerate(result.data):
    filename = f"image_{i}.png"
    if image.b64_json:
        with open(filename, "wb") as f:
            f.write(base64.b64decode(image.b64_json))
    elif image.url:
        urllib.request.urlretrieve(image.url, filename)
    print("saved", filename)

با Node.js

import fs from "node:fs/promises";
import OpenAI from "openai";

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

const result = await client.images.generate({
  model: "openai/gpt-image-2",
  prompt: "Isometric illustration of a small bakery in Tabriz, soft colors",
  size: "1536x1024",
});

await fs.writeFile("bakery.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log("saved bakery.png");

نوشتن prompt خوب

• جزئیات بصری بدهید: موضوع، سبک (آبرنگ، عکس واقعی، تخت، سه‌بعدی)، نور، زاویه‌ی دید و رنگ‌ها.
• prompt انگلیسی معمولاً نتیجه‌ی دقیق‌تری دارد. مدل‌ها prompt فارسی را می‌فهمند، ولی اگر نتیجه دلخواه نبود، همان توضیح را انگلیسی امتحان کنید. می‌توانید ابتدا با یک مدل چت، توضیح فارسی کاربر را به prompt انگلیسی تبدیل کنید.
• متن داخل تصویر را کم نگه دارید. نوشتن متن فارسی داخل تصویر هنوز برای بیشتر مدل‌ها دشوار است و حروف ممکن است جدا یا اشتباه رسم شوند. بهتر است متن را بعداً با ابزار طراحی روی تصویر بگذارید.
• مدل‌ها ممکن است prompt شما را برای ایمنی یا کیفیت بازنویسی کنند. در این حالت متن بازنویسی‌شده، اگر مدل آن را برگرداند، در revised_prompt می‌آید.

محدودیت‌های محتوایی

ارائه‌دهنده‌های مدل برای تولید تصویر سیاست محتوایی دارند. درخواستی که با این سیاست‌ها مغایر باشد رد می‌شود و پیام خطا دلیل را توضیح می‌دهد. تکرار خودکار چنین درخواستی را در کدتان پیاده نکنید.

هزینه

هزینه‌ی تولید تصویر به ازای هر تصویر محاسبه می‌شود و به مدل، اندازه و کیفیت بستگی دارد. برای مثال تصویر بزرگ‌تر یا با کیفیت بالاتر گران‌تر است و با n=4 هزینه‌ی چهار تصویر کسر می‌شود. برخی مدل‌ها (مثل openai/gpt-image-2) علاوه بر تصویر، برای توکن‌های prompt هم هزینه دارند. قیمت دقیق هر ترکیب را در صفحه‌ی قیمت‌ها ببینید و نحوه‌ی تبدیل دلار به تومان را در قیمت‌گذاری و صورتحساب بخوانید.

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