تولید و ویرایش تصویر
ساخت تصویر، تنظیم اندازه و فرمت، و استفاده از تصویر مرجع.
ساخت و ویرایش تصویر
POST /v1/studio/image با مجوز studio:write تصویر می‌سازد. prompt اجباری است؛ model، quality، outputFormat و references اختیاری‌اند. برای ویرایش، تصویر PNG/JPEG/WebP را به‌صورت dataUrl در references بفرستید.
اندازهٔ خودکار
aspectRatio: "auto" جهت و ابعاد را از متن فارسی یا انگلیسی دنبال می‌کند. اگر متن اندازه نداشته باشد، نسبت تصویر مرجع حفظ می‌شود. درخواست‌های قدیمی بدون فیلد اندازه همچنان 1:1 هستند. اندازهٔ دستی بر جهت متن اولویت دارد.
import json, os, urllib.request, urllib.error
payload = {
"model": "google/gemini-2.5-flash-image",
"prompt": "یک پوستر عمودی مینیمال از یک گل سفید",
"aspectRatio": "auto"
}
request = urllib.request.Request(
"https://api.sarovi.ir/v1/studio/image",
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers={
"Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
"Content-Type": "application/json"
},
method="POST"
)
try:
with urllib.request.urlopen(request, timeout=300) as response:
result = json.load(response)
print(result)
except urllib.error.HTTPError as error:
detail = json.load(error)
raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from errorکلید را در متغیر محیطی SAROVI_API_KEY قرار بده. بدون نصب کتابخانه؛ با Python استاندارد.
اندازهٔ فایل نهایی
برای خروجی دقیق، size: "1200x630" و fit: "pad" بفرستید. این اندازهٔ فایل نهایی است و لزوماً اندازهٔ بومی مدل نیست. pad تصویر کامل را بدون کشیدگی با حاشیه حفظ می‌کند؛ crop لبه‌ها را می‌بُرد تا قاب پر شود. پیش‌فرض pad است. نسبت‌های دلخواه مانند aspectRatio: "7:4" نیز پذیرفته می‌شوند؛ مدل نزدیک‌ترین قاب پشتیبانی‌شده را می‌سازد و خروجی به نسبت درخواستی تنظیم می‌شود.
هر ضلع بین 64 و 4096 پیکسل، کل فایل حداکثر 4 مگاپیکسل و نسبت بین 1:8 و 8:1 است. ابعاد نامعتبر یا متناقض با نسبت صریح، پیش از اجرا و مصرف اعتبار رد می‌شوند. خروجی width، height و sizing را شامل ابعاد اصلی و روش تنظیم برمی‌گرداند.
سازگاری Responses
POST /v1/responses با یک مدل تصویر و مجوز studio:write نیز کار می‌کند. داخل tools یک image_generation بفرستید؛ گزینه‌های size، aspect_ratio و fit همان رفتار را دارند. size: "auto" واقعاً از متن یا مرجع پیروی می‌کند. کیفیت، output_format، background و action بر اساس مدل کنترل می‌شوند. برای ویرایش از input_image با data URL استفاده کنید.
import json, os, urllib.request, urllib.error
payload = {
"model": "google/gemini-2.5-flash-image",
"input": "یک بنر مینیمال از یک گل سفید",
"tools": [
{
"type": "image_generation",
"size": "1200x630",
"fit": "pad"
}
],
"store": False
}
request = urllib.request.Request(
"https://api.sarovi.ir/v1/studio/image",
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers={
"Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
"Content-Type": "application/json"
},
method="POST"
)
try:
with urllib.request.urlopen(request, timeout=300) as response:
result = json.load(response)
print(result)
except urllib.error.HTTPError as error:
detail = json.load(error)
raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from errorکلید را در متغیر محیطی SAROVI_API_KEY قرار بده. بدون نصب کتابخانه؛ با Python استاندارد.
پاسخ image_generation_call با تصویر base64 است. stream:true رویدادهای SSE را پس از آماده‌شدن خروجی می‌دهد؛ تصویر جزئی، تصویر از URL خارجی، previous_response_id و ابزار تصویر زیر مدل چت پشتیبانی نمی‌شوند. هزینه یک بار در همان موتور Studio تسویه می‌شود. نتیجهٔ فایل ذخیره‌شده از /v1/files/{id} قابل دریافت است. کلید Idempotency-Key را برای تکرار همان درخواست حفظ کنید.
قرارداد API 1.6.0 · تاریخچهٔ تغییرات