چهار قابلیت تازه در API هوشواره: ویرایش عکس، تصویر 4K، افزایش کیفیت و ویدیو از روی عکس

تیم هوشواره

۱۴۰۵/۰۷/۰۷ · 6 دقیقه مطالعه

API هوش مصنوعی ویرایش عکس با هوش مصنوعی تصویر 4K افزایش کیفیت تصویر آپ‌اسکیل ویدیو از روی عکس image to video OpenAI API توسعه‌دهندگان

اگر نرم‌افزار، ربات یا سایتی دارید که از طریق API به هوشواره وصل است، از امروز چهار کار تازه از همان کلید برمی‌آید: ویرایش عکس، تصویر 4K، افزایش کیفیت و ویدیو از روی عکس. همه با همان قالب آشنای OpenAI کار می‌کنند، پس اگر پیش‌تر با آن کد نوشته‌اید تقریباً چیزی عوض نمی‌شود. در این مقاله می‌بینیم هرکدام چه می‌کند، چطور صدایش بزنید و روی چه چیزهایی می‌شود حساب کرد.

چهار قابلیت در یک نگاه

قابلیت	مسیر	در یک جمله
ویرایش عکس	`POST /v1/images/edits`	یک عکس و یک دستور متنی می‌فرستید و عکسِ ویرایش‌شده را می‌گیرید.
تصویر 4K	`resolution: "4K"` روی `/v1/images/generations`	خروجیِ بزرگ، روی مدل‌هایی که 4K می‌سازند.
افزایش کیفیت	`POST /v1/images/upscale`	بزرگ‌نمایی و شفاف‌سازیِ عکس تا ۱۶ برابر.
ویدیو از روی عکس	`input_reference` روی `/v1/videos`	عکسِ شما نقطه‌ی شروعِ کلیپ می‌شود.

۱. ویرایش عکس با یک دستور ساده

مسیر تازه‌ی /v1/images/edits دقیقاً همان قراردادی است که images.edit در کتابخانه‌ی رسمی OpenAI انتظار دارد؛ یعنی کدِ موجودتان فقط با عوض‌کردنِ نشانیِ پایه کار می‌کند:

from openai import OpenAI
client = OpenAI(base_url="https://chatblzn.com/v1", api_key="YOUR_API_KEY")

r = client.images.edit(
    model="IMAGE_MODEL_ID",
    image=open("room.jpg", "rb"),
    prompt="make the wall olive green",
)

تصویرهای مرجع: می‌توانید چند تصویر بفرستید؛ اولی ویرایش می‌شود و بقیه راهنما هستند — مثلاً عکسِ یک محصول که باید در صحنه قرار بگیرد، یا نمونه‌ای از سبکِ دلخواه.
ماسک: با یک PNG هم‌اندازه‌ی عکس می‌گویید کجا تغییر کند. هم قراردادِ OpenAI (ناحیه‌ی شفاف یعنی «این‌جا را عوض کن») پذیرفته می‌شود و هم ماسکِ سیاه‌وسفید.
حریم خصوصی: اطلاعاتِ جانبیِ عکس، مثلِ مکانِ عکاسی، پیش از رسیدن به مدل پاک می‌شود.

یک نکته‌ی صادقانه درباره‌ی ماسک: امروز هیچ‌کدام از مدل‌ها مرزِ ماسک را به‌شکلِ قطعی رعایت نمی‌کنند. ناحیه‌ای که مشخص می‌کنید به‌صورتِ راهنما به مدل داده می‌شود؛ معمولاً رعایتش می‌کند، اما ممکن است کمی بیرون از آن را هم تغییر دهد.
— تیم هوشواره

۲. تصویر 4K

کافی است در درخواستِ ساختِ تصویر، فیلدِ resolution را بفرستید:

{
  "model": "IMAGE_MODEL_ID",
  "prompt": "a wooden boat on a misty lake at dawn",
  "resolution": "4K",
  "size": "1536x1024"
}

در آزمایشِ ما، یکی از مدل‌ها برای همین درخواست تصویری ۴۰۹۶ در ۲۷۳۲ پیکسل ساخت، در حدودِ چهارده ثانیه. چند نکته:

همه‌ی مدل‌ها 4K نمی‌سازند. در فهرستِ مدل‌ها، هر مدل رزولوشن‌هایی را که پشتیبانی می‌کند در فیلدِ resolutions اعلام می‌کند.
size نسبتِ تصویر را تعیین می‌کند و اندازه‌ی دقیقِ پیکسلی را خودِ مدل انتخاب می‌کند؛ ابعادِ واقعیِ هر تصویر در پاسخ می‌آید.
اگر مدلی رزولوشنِ خواسته‌شده را نسازد، درخواست پیش از هر هزینه‌ای رد می‌شود و پیامِ خطا رزولوشن‌های مجازِ همان مدل را می‌گوید؛ دیگر تصویری کوچک‌تر از خواسته‌ی شما بی‌صدا تحویل داده نمی‌شود.

۳. افزایش کیفیت و وضوحِ عکس (Upscale)

مسیرِ /v1/images/upscale یک عکس را ۲، ۴، ۸ یا ۱۶ برابر بزرگ می‌کند و جزئیاتش را بازسازی می‌کند — کاری که به آن فراتفکیک‌پذیری هم می‌گویند. مدلِ این بخش Magnific Precision Upscaler است و برای عکس، عکسِ پُرنویز و تصویرسازی حالتِ جداگانه دارد.

curl -X POST https://chatblzn.com/v1/images/upscale \
  -H "Authorization: Bearer $HV_KEY" \
  -F [email protected] -F scale=4 -F flavor=photo

چون خروجی می‌تواند ده‌ها مگابایت باشد، پاسخ یک لینکِ دریافت است که با همان کلید و تا ۲۴ ساعت کار می‌کند.
قیمت از قبل معلوم است: به اندازه‌ی خروجی بستگی دارد و خروجیِ بزرگ‌تر از ۴۰۹۶ پیکسل در پله‌ی بالاتری است. مبلغِ دقیق در همان پاسخ می‌آید.
خروجی حداکثر ۸۱۹۲ پیکسل در هر ضلع است؛ اگر ضریب بزرگ‌تر از این شود، پیامِ خطا بزرگ‌ترین ضریبِ مجاز برای همان عکس را می‌گوید.

۴. ویدیو از روی عکس

تا امروز API فقط از روی متن ویدیو می‌ساخت. حالا کافی است عکسِ آغاز را در فیلدِ input_reference بفرستید — همان نامی که API ویدیوی OpenAI به کار می‌برد. مدل‌هایی که تصویرِ پایان هم می‌پذیرند، با last_frame میانِ دو تصویر ویدیو می‌سازند.

curl -X POST https://chatblzn.com/v1/videos \
  -H "Authorization: Bearer $HV_KEY" \
  -F model=VIDEO_MODEL_ID -F seconds=5 \
  -F prompt="the boat drifts slowly forward" \
  -F [email protected]

ساختِ ویدیو مثلِ قبل در پس‌زمینه انجام می‌شود: یک شناسه می‌گیرید، وضعیت را دنبال می‌کنید و در پایان فایل را دریافت می‌کنید. بعضی مدل‌ها روی عکسی که چهره‌ی یک انسانِ واقعی دارد ویدیو نمی‌سازند؛ در این حالت کار با پیامِ روشن متوقف می‌شود و هزینه‌ای کسر نمی‌شود.

از کجا بفهمم هر مدل چه کاری می‌کند؟

فهرستِ مدل‌ها (GET /v1/models) حالا برای هر مدل می‌گوید چه کاری از آن برمی‌آید، تا لازم نباشد با آزمون و خطا پیدا کنید:

مدل‌های تصویر: edits (ویرایش می‌کند یا نه)، max_input_images و resolutions.
مدل‌های ویدیو: modes (از روی متن، از روی عکس، یا هر دو) و frame_images.
مدل‌های افزایش کیفیت: نوعِ upscale و فیلدِ scale_factors.

قاعده‌ی ما ساده است: اگر کاری انجام‌شدنی نیست، پیش از هر هزینه‌ای و با پیامی که راهِ درست را نشان می‌دهد می‌گوییم — نه اینکه چیزِ دیگری تحویل بدهیم و پولش را بگیریم.
— تیم هوشواره

هزینه چطور حساب می‌شود؟

مثلِ بقیه‌ی API: پیش از کار، اعتبارِ لازم رزرو و پس از کار به مبلغِ واقعی تسویه می‌شود. اگر کار شکست بخورد یا انجام‌شدنی نباشد، چیزی کسر نمی‌شود. مبلغِ هر درخواست در فیلدِ usage.cost پاسخ و در صفحه‌ی «مصرف» پنل می‌آید. کلیدِ «پکیج API» از اعتبارِ پلنِ API و کلیدِ «کیف‌پول» از اعتبارِ حساب برداشت می‌کند.

پرسش‌های متداول

کدی که با کتابخانه‌ی رسمی OpenAI نوشته‌ام کار می‌کند؟

بله. ویرایش و ساختِ تصویر همان قالبِ OpenAI را دارند و کافی است base_url را روی نشانیِ هوشواره بگذارید. افزایش کیفیت در OpenAI معادلی ندارد و یک مسیرِ ساده‌ی جداگانه است.

می‌توانم به‌جای خودِ عکس، لینکش را بفرستم؟

نه؛ عکس را به‌صورتِ فایل، data URL یا base64 بفرستید. JPEG، PNG و WebP تا ۲۰ مگابایت پذیرفته می‌شوند.

خروجی‌ها تا کی در دسترس‌اند؟

ویرایش و ساختِ تصویر، خودِ عکس را در همان پاسخ برمی‌گردانند. نتیجه‌ی افزایش کیفیت تا ۲۴ ساعت از لینکِ دریافت در دسترس است و ویدیو تا پایانِ مدتِ نگهداریِ حسابِ شما؛ برای نگهداریِ دائمی، خودتان ذخیره‌شان کنید.

در استودیوی سایت هم این امکانات هست؟

ویرایشِ عکس و ساختِ ویدیو از روی عکس از قبل در استودیو هست. تصویرِ 4K و افزایش کیفیت فعلاً فقط از طریقِ API در دسترس‌اند.

راهنمای کامل را کجا ببینم؟

همه‌ی مسیرها با نمونه‌ی آماده‌ی curl و Python در صفحه‌ی API پنلِ کاربری آمده است؛ خلاصه‌ی عمومی هم در صفحه‌ی توسعه‌دهندگان است.

جمع‌بندی

با این چهار قابلیت، کارهایی که در استودیو با عکس و ویدیو انجام می‌دادید حالا از نرم‌افزارِ خودتان هم ممکن است — و فراتر از آن: تصویرِ 4K و افزایش کیفیت تا ۱۶ برابر. اگر تازه با API هوشواره آشنا می‌شوید، مقاله‌ی اتصال ابزارهای برنامه‌نویسی به هوشواره نقطه‌ی شروعِ خوبی است. مدل‌ها را در کاتالوگ مدل‌ها ببینید و کلید را از صفحه‌ی API پنل بسازید. حساب ندارید؟ ثبت‌نام کمتر از یک دقیقه طول می‌کشد.