شما ها

وضعیت را با GET /generations/{id}/ بررسی کنید.

نوع مدیای تسک.

مدل، همان‌طور که در درخواست فرستاده‌اید.

همیشه processing؛ هنوز چیزی ساخته نشده است.

از قبل کسر شده است. این قیمت نهایی است، به‌جز در تسک‌های edit/extend مدل seedance25 که این مبلغ رزرو اعتبار است و پس از تحویل، بخشی از آن بازگردانده می‌شود.

مدل، همان‌طور که در درخواست فرستاده‌اید.

تا وقتی پرووایدر نتیجه را برنگرداند، processing است. وضعیت‌های نهایی succeeded و failed هستند و هیچ‌کدام پس از آن تغییر نمی‌کنند.

مقداری که هنگام ارسال کسر شده است. هرگز تغییر نمی‌کند.

مقداری که از آن پس بازگشته است: کل credits_charged پس از بازگشت اعتبار یک تولید failed، هزینه ثانیه‌های تحویل‌نشده وقتی ویدیوی ثانیه‌ای دست‌کم 2 ثانیه کوتاه‌تر برگردد، یا بخش استفاده‌نشده رزرو اعتبار edit/extend در seedance25 پس از تسویه. credits_charged منهای این مقدار، هزینه واقعی تولید است.

تا وضعیت succeeded خالی است. ساختار آیتم‌ها به type بستگی دارد:

• image و video: url و thumbnail. ویدیو همیشه دقیقاً یک آیتم برمی‌گرداند.
• music: دو آیتم، هر کدام با title، url، cover_image و duration.
• speech: یک آیتم با url.

همه لینک‌ها signed هستند و 24 ساعت پس از ساخته شدن منقضی می‌شوند.

فقط وقتی وجود دارد که status برابر failed باشد.

از جدیدترین به قدیمی‌ترین. تولیدی که رکوردش حذف شده باشد در فهرست نمی‌آید.

صفحه‌ای که برگردانده شده است.

اینکه صفحه بعدی وجود دارد یا نه.

لینک signed مدیای ساخته‌شده.

لینک signed یک پیش‌نمایش ثابت.

عنوانی که مدل انتخاب کرده، یا عنوانی که در حالت سفارشی خودتان داده‌اید.

لینک signed فایل mp3.

لینک signed تصویر کاور ساخته‌شده.

طول ترک بر حسب ثانیه.

لینک signed فایل mp3.

یک map از آیدی مدل به آبجکت قابلیت‌های آن. هر مورد name و pricing دارد؛ کلیدهای دیگر پارامترهای مدل را توصیف می‌کنند و از مدلی به مدل دیگر فرق دارند: aspect_ratios، durations، qualities، default_quality، model_levels، mode_model_levels، modes، defaults، sync_modes، output_formats، max_prompt_chars، max_input_images، image_input، video_input، audio_input، requires_video_input، requires_audio_input، has_audio و notes. مدل‌های chatgpt-image-2.5-* فیلدهای levels، default_level و backgrounds را هم دارند و pricing آن‌ها held_credits_by_level (به ترتیب سطح، کیفیت و نسبت تصویر) و held_credits_per_input_image را اضافه می‌کند؛ pricing مدل nano-banana-2-1 هم credits_per_input_image و rounding دارد. مدل‌های موسیقی max_prompt_chars_simple_mode و max_style_chars را هم دارند و مدل‌های گفتار max_lines، min_characters، max_unique_voices، voices و languages را.

URLهای تصویر https:// که به‌صورت عمومی در دسترس باشند. لینک‌های مدیای هوشا با خطای invalid_image_url رد می‌شوند؛ آن فایل‌ها را از طریق uploads بفرستید. در multipart این فیلد را تکرار کنید.

آیدی‌های آپلود دریافتی از POST /uploads/. هر آیدی یک‌بارمصرف است و حدود 20 دقیقه پس از آپلود منقضی می‌شود. /images/ آیدی‌های آپلود را فقط از همین فیلد می‌خواند؛ آیدی‌ای که در image1 فرستاده شود نادیده گرفته می‌شود.

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

آنچه باید ساخته شود، یا اینکه ورودی‌ها چطور ویرایش شوند. اگر طول آن از max_prompt_chars مدل بیشتر باشد، با خطای prompt_too_long رد می‌شود.

URLهای تصویر https:// که به‌صورت عمومی در دسترس باشند. لینک‌های مدیای هوشا با خطای invalid_image_url رد می‌شوند؛ آن فایل‌ها را از طریق uploads بفرستید. در multipart این فیلد را تکرار کنید.

آیدی‌های آپلود دریافتی از POST /uploads/. هر آیدی یک‌بارمصرف است و حدود 20 دقیقه پس از آپلود منقضی می‌شود. /images/ آیدی‌های آپلود را فقط از همین فیلد می‌خواند؛ آیدی‌ای که در image1 فرستاده شود نادیده گرفته می‌شود.

پیش‌فرض در chatgpt-image-2.0، مدل‌های chatgpt-image-2.5-* و nano-banana-2-1 برابر auto و در chatgpt-image-1.5 و grok-imagine-2 برابر 1:1 است. این مدل‌ها مقدار را بررسی می‌کنند و نسبت پشتیبانی‌نشده در آن‌ها با خطای invalid_aspect_ratio رد می‌شود. بقیه مدل‌ها نسبتی را که نمی‌توانند بسازند، به‌جای رد کردن، جایگزین می‌کنند: hoosha-v1 با auto می‌سازد، nano-banana-2-pro و seedream4 با 1:1 و flux_kontext با 16:9، حتی برای پیش‌فرض 4:3. در محدوده aspect_ratios هر مدل در GET /models/ بمانید.

فقط برای مدل‌های دارای سطح‌بندی کیفیت (nano-banana-2-1، nano-banana-2-pro، chatgpt-image-2.0 و مدل‌های chatgpt-image-2.5-*)؛ سطح قیمت را تعیین می‌کند و پیش‌فرض آن در nano-banana-2-1 برابر 1K است. بقیه مدل‌ها آن را نادیده می‌گیرند. با نام resolution هم پذیرفته می‌شود؛ اگر هر دو فرستاده شوند، quality اولویت دارد. هر مقدار دیگری با خطای invalid_quality رد می‌شود.

فقط برای مدل‌های chatgpt-image-2.5-*؛ بقیه مدل‌ها آن را نادیده می‌گیرند. low و medium با قیمت جدول محاسبه می‌شوند. high، xhigh و max به یک aspect_ratio مشخص و کیفیت 2K یا 4K نیاز دارند، اعتبار جدول سطح‌ها را رزرو می‌کنند و پس از تحویل تصویر با هزینه واقعی تسویه می‌شوند. هر مقدار دیگری با خطای invalid_level رد می‌شود.

فقط برای مدل‌های chatgpt-image-2.5-* و در همه سطح‌ها؛ بقیه مدل‌ها آن را نادیده می‌گیرند. هر مقدار دیگری با خطای invalid_background رد می‌شود.

فقط برای nano-banana-2-pro؛ بقیه مدل‌ها آن را نادیده می‌گیرند. هر مقدار دیگری با خطای invalid_output_format رد می‌شود.

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

آنچه باید ساخته شود، یا اینکه ورودی‌ها چطور ویرایش شوند. اگر طول آن از max_prompt_chars مدل بیشتر باشد، با خطای prompt_too_long رد می‌شود.

URLهای تصویر https:// که به‌صورت عمومی در دسترس باشند. لینک‌های مدیای هوشا با خطای invalid_image_url رد می‌شوند؛ آن فایل‌ها را از طریق uploads بفرستید. در multipart این فیلد را تکرار کنید.

آیدی‌های آپلود دریافتی از POST /uploads/. هر آیدی یک‌بارمصرف است و حدود 20 دقیقه پس از آپلود منقضی می‌شود. /images/ آیدی‌های آپلود را فقط از همین فیلد می‌خواند؛ آیدی‌ای که در image1 فرستاده شود نادیده گرفته می‌شود.

پیش‌فرض در chatgpt-image-2.0، مدل‌های chatgpt-image-2.5-* و nano-banana-2-1 برابر auto و در chatgpt-image-1.5 و grok-imagine-2 برابر 1:1 است. این مدل‌ها مقدار را بررسی می‌کنند و نسبت پشتیبانی‌نشده در آن‌ها با خطای invalid_aspect_ratio رد می‌شود. بقیه مدل‌ها نسبتی را که نمی‌توانند بسازند، به‌جای رد کردن، جایگزین می‌کنند: hoosha-v1 با auto می‌سازد، nano-banana-2-pro و seedream4 با 1:1 و flux_kontext با 16:9، حتی برای پیش‌فرض 4:3. در محدوده aspect_ratios هر مدل در GET /models/ بمانید.

فقط برای مدل‌های دارای سطح‌بندی کیفیت (nano-banana-2-1، nano-banana-2-pro، chatgpt-image-2.0 و مدل‌های chatgpt-image-2.5-*)؛ سطح قیمت را تعیین می‌کند و پیش‌فرض آن در nano-banana-2-1 برابر 1K است. بقیه مدل‌ها آن را نادیده می‌گیرند. با نام resolution هم پذیرفته می‌شود؛ اگر هر دو فرستاده شوند، quality اولویت دارد. هر مقدار دیگری با خطای invalid_quality رد می‌شود.

فقط برای مدل‌های chatgpt-image-2.5-*؛ بقیه مدل‌ها آن را نادیده می‌گیرند. low و medium با قیمت جدول محاسبه می‌شوند. high، xhigh و max به یک aspect_ratio مشخص و کیفیت 2K یا 4K نیاز دارند، اعتبار جدول سطح‌ها را رزرو می‌کنند و پس از تحویل تصویر با هزینه واقعی تسویه می‌شوند. هر مقدار دیگری با خطای invalid_level رد می‌شود.

فقط برای مدل‌های chatgpt-image-2.5-* و در همه سطح‌ها؛ بقیه مدل‌ها آن را نادیده می‌گیرند. هر مقدار دیگری با خطای invalid_background رد می‌شود.

فقط برای nano-banana-2-pro؛ بقیه مدل‌ها آن را نادیده می‌گیرند. هر مقدار دیگری با خطای invalid_output_format رد می‌شود.

اولین تصویر ورودی، به‌صورت فایل.

دومین تصویر ورودی. تا جایی که مدل اجازه می‌دهد با image3، image4، … ادامه دهید.

با نام mode هم پذیرفته می‌شود؛ اگر هر دو فرستاده شوند، model اولویت دارد. مقدار ناشناخته با خطای invalid_model رد می‌شود.

برای همه مدل‌ها به‌جز kling-motion، lipsync و genjutsu الزامی است. اگر طول آن از max_prompt_chars مدل بیشتر باشد، درخواست رد می‌شود.

مدت بر حسب ثانیه، به‌صورت string، از میان durations مدل در GET /models/؛ هر مقدار دیگری رد می‌شود و اگر آن را نفرستید، پیش‌فرض مدل به کار می‌رود. حتماً به‌صورت string بفرستید: عدد JSON از بررسی عبور می‌کند، اما مدل در این حالت مدت پیش‌فرض خودش را می‌سازد. در مواردی که مدت از ورودی گرفته می‌شود نادیده گرفته می‌شود: kling-motion، lipsync، genjutsu، gemini-omni-video وقتی video1 فرستاده شود، و seedance25 در seedance_mode: edit.

یکی از 480، 720، 1080 یا 4k بسته به مدل، از میان qualities آن در GET /models/؛ هر مقدار دیگری رد می‌شود و اگر آن را نفرستید، پیش‌فرض مدل به کار می‌رود. مثل duration، این مقدار را هم به‌صورت string بفرستید. kling فقط کیفیت 1080 دارد و lipsync فقط auto را می‌پذیرد.

مجموعه مقادیر هر مدل را از GET /models/ بگیرید. با image، در مدل‌هایی که پشتیبانی می‌کنند، خروجی از تصویر ورودی پیروی می‌کند (این مقدار به‌صورت auto یا adaptive برای پرووایدر فرستاده می‌شود). هر مقدار خارج از مجموعه مدل رد می‌شود؛ اگر آن را نفرستید، پیش‌فرض مدل به کار می‌رود.

نسخه مورد نظر را در خانواده مدل انتخاب می‌کند و قیمت هم به آن بستگی دارد.

مقدار خارج از مجموعه مدل رد می‌شود. آن را به‌صورت string بفرستید: عدد JSON مانند 2.6 خوانده نمی‌شود و پیش‌فرض به کار می‌رود. lipsync در سطح v2-pro به ورودی ویدیویی نیاز دارد؛ v3 یا یک ویدیو می‌گیرد یا یک تصویر. genjutsu در سطح lite ویدیوی رفرنسی با حداکثر 15 ثانیه می‌گیرد. seedance2 کیفیت‌های 1080 و 4k را فقط در سطح pro می‌سازد؛ درخواست آن‌ها در سطح دیگر رد می‌شود، نه اینکه بی‌خبر به کیفیت پایین‌تر تبدیل شود.

فقط برای veo3. اگر آن را نفرستید، از روی تعداد تصویرهای ورودی تعیین می‌شود: بدون تصویر، text-to-video؛ یک تصویر، first-frame-last-frame با آن تصویر به‌عنوان فریم اول؛ دو یا سه تصویر، image-to-video با تصویرها به‌عنوان رفرنس. برای استفاده از دو تصویر به‌عنوان فریم اول و آخر، first-frame-last-frame را صریحاً بفرستید. image-to-video بین 1 تا 3 تصویر و first-frame-last-frame یک یا دو تصویر می‌گیرد.

فقط برای seedance2 و seedance25. اگر آن را نفرستید، این‌طور تعیین می‌شود: بدون تصویر، text-to-video؛ یک تصویر، image-to-video؛ دو تصویر، در seedance2 حالت first-frame-last-frame اما در seedance25 حالت reference-to-video؛ سه تصویر یا بیشتر، یا هر video1/audio1، حالت reference-to-video.

reference-to-video صحنه چندوجهی است و دست‌کم به یک تصویر یا ویدیو نیاز دارد. محدودیت‌ها:

edit و extend فقط در seedance25 وجود دارند و دست‌کم به یک ویدیوی ورودی نیاز دارند. در edit خروجی از ویدیوی ورودی پیروی می‌کند، پس مدت، نسبت تصویر و حالت از آن گرفته می‌شوند و هر ویدیوی ورودی باید دست‌کم 4 ثانیه باشد؛ در این حالت اعتبار به اندازه دو برابر ثانیه‌های ورودی به‌علاوه 3 ثانیه با نرخ «با ویدیو» رزرو می‌شود. extend ویدیو را ادامه می‌دهد و هزینه ورودی به‌علاوه duration درخواستی را کسر می‌کند. هزینه هر دو حالت پس از تحویل، بر اساس ثانیه‌های ورودی به‌علاوه ثانیه‌های تحویل‌شده تسویه می‌شود.

برای seedance2 و seedance25. قیمت در هر دو حالت یکسان است، پس روشن گذاشتن آن هیچ هزینه اضافه‌ای ندارد.

دیگر هیچ اثری ندارد. درخواست‌های متن به ویدیوی seedance2 همیشه صحنه را بر پایه جست‌وجوی وب می‌سازند.

فقط برای seedance25.

فقط برای lipsync. تعیین می‌کند ویدیو و صوتی با طول‌های متفاوت چطور با هم تطبیق داده شوند: bounce ویدیو را رفت‌وبرگشتی پخش می‌کند، loop آن را تکرار می‌کند، cut_off طولانی‌تر را کوتاه می‌کند، silence صوت را با سکوت تکمیل می‌کند و remap سرعت ویدیو را تغییر می‌دهد. قیمت از طول خروجی پیروی می‌کند: طول صوت، به‌جز در silence که طول بلندتر از این دو و در cut_off که طول کوتاه‌تر ملاک است.

برای kling-motion. تعیین می‌کند جهت قرارگیری شخصیت از کدام منبع گرفته شود. با image، ویدیوی رفرنس حداکثر 10 ثانیه می‌تواند باشد.

فقط برای kling-motion با model_level: 3.0. تعیین می‌کند پس‌زمینه از کدام منبع گرفته شود.

تصویرهای ورودی هاست‌شده، فقط با https:// و نه روی هاست‌های مدیای هوشا؛ این URLها همان‌طور که هستند به پرووایدر داده می‌شوند. آن‌ها کم‌شماره‌ترین جایگاه‌های خالی image1…imageN را پر می‌کنند: اگر فقط image2 را فرستاده باشید، اولین URL به image1 تبدیل می‌شود. این تصویرها در سقف تصویر مدل حساب می‌شوند.

تصویر ورودی: یک آیدی آپلود (/videos/ آیدی‌های آپلود را فقط از همین فیلدهای شماره‌دار می‌خواند، نه از uploads)، یا یک بخش فایل در multipart (png، jpg، jpeg، webp یا gif، حداکثر 10,000,000 بایت، بدون تبدیل). با image2، image3، … ادامه دهید.

تعداد تصویرهایی که هر مدل می‌خواند: seedance25 تا 30، seedance2 تا 9، genjutsu تا 8 (دست‌کم 1 تصویر الزامی است)، grok-imagine تا 7، gemini-omni-video تا 7 (و وقتی video1 فرستاده شود تا 5)، veo3 تا 3، kling3 فقط 1، kling-motion دقیقاً 1، lipsync یک تصویر وقتی video1 فرستاده نشود (در صورت وجود ویدیو نادیده گرفته می‌شود)، runway و seedance فقط image1. در kling، image2 فریم پایانی است. فقط grok-imagine و genjutsu تصویرهای اضافه را با خطای too_many_images رد می‌کنند؛ در بقیه مدل‌ها تصویرهای بیشتر از حد مجاز کنار گذاشته می‌شوند. در first-frame-last-frame، image1 فریم اول و image2 فریم آخر است.

ویدیوی رفرنس، به‌صورت آیدی آپلود. برای kling-motion (3 تا 30 ثانیه)، برای genjutsu (5 تا 30 ثانیه، در lite 5 تا 15 ثانیه، حداکثر 200 مگابایت) و برای lipsync با model_level: v2-pro الزامی است؛ در v3 اختیاری است و در نبود آن از image1 استفاده می‌شود. gemini-omni-video فقط video1 را می‌خواند (حداکثر 10 ثانیه و 100 مگابایت). صحنه‌های رفرنس seedance25 تا video10 و صحنه‌های رفرنس seedance2 تا video3 می‌پذیرند.

صوت رفرنس، به‌صورت آیدی آپلود. برای lipsync الزامی است؛ در این مدل طول صوت (2 تا 30 ثانیه، و همراه با تصویر 2 تا 15 ثانیه) مبنای محاسبه هزینه است و فایل‌های بزرگ‌تر از 10 مگابایت رد می‌شوند. صحنه‌های رفرنس seedance25 تا audio10 و صحنه‌های رفرنس seedance2 تا audio3 می‌پذیرند.

در حالت ساده، توضیحی درباره ترک (حداکثر 3,000 کاراکتر). در حالت سفارشی، متن ترانه (حداکثر 5,000 کاراکتر).

اختیاری. هر مقدار خارج از کاتالوگ با خطای invalid_model رد می‌شود.

با false ترک را در prompt توصیف می‌کنید و بقیه کار را به مدل می‌سپارید. با true، prompt متن ترانه است و style و title اعمال می‌شوند.

ژانر و سبک تنظیم. فقط در حالت سفارشی.

فقط در حالت سفارشی. به 79 واحد UTF-16 کوتاه می‌شود (هر ایموجی دو واحد حساب می‌شود) و اگر آن را نفرستید، از پرامپت یا سبک استفاده می‌شود.

ساخت ترک بدون آواز.

یک خط از دیالوگ. تگ‌های درون‌خطی مانند [laughs] یا [whispers] نحوه ادای جمله را هدایت می‌کنند و خوانده نمی‌شوند؛ خطی که پس از حذف تگ‌ها و ایموجی‌ها هیچ متن قابل خواندنی در آن نماند، رد می‌شود.

آیدی صدا. پیش‌فرض آن شایان (EkK5I93UQWFDigLMpZcX) است.

خط‌های دیالوگ، به‌ترتیب. حداکثر 6 خط و 10 صدای متفاوت، با مجموع طول متن بین 5 تا 5,000 کاراکتر. هزینه بر اساس همین مجموع طول محاسبه می‌شود.

اختیاری. هر مقدار خارج از کاتالوگ با خطای invalid_model رد می‌شود.

مقدار 0 خلاقانه، 0.5 طبیعی و 1 پایدار. به‌صورت عدد یا string پذیرفته می‌شود؛ هر مقداری جز این سه رد می‌شود.

string خالی یعنی تشخیص خودکار زبان. در غیر این صورت، یکی از کدهای پشتیبانی‌شده.