API مدیای هوشا

با API هوشا می‌توانید تصویر، ویدیو، موسیقی و گفتار را با پیشرفته‌ترین مدل‌های روز تولید کنید؛ همه با یک کلید API، یک موجودی اعتبار و یک روال یکسان برای بررسی وضعیت (پولینگ).

شروع سریع

کد
# 1. در console.hoosha.com یک کلید API بسازید، سپس یک تسک ارسال کنید:
curl https://api.hoosha.com/api/v1/images/ \
  -H "Authorization: Bearer sk-hoosha-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "hoosha-v1", "prompt": "a red fox in autumn leaves", "aspect_ratio": "1:1"}'
# → 202 {"id": "3c1f...", "status": "processing", "credits_charged": 5, ...}

# 2. وضعیت را بررسی کنید تا از `processing` خارج شود:
curl https://api.hoosha.com/api/v1/generations/3c1f.../ \
  -H "Authorization: Bearer sk-hoosha-..."
# → 200 {"status": "succeeded", "output": [{"url": "https://...", "thumbnail": "https://..."}]}

همه pathها با اسلش تمام می‌شوند؛ درخواست‌ها را دقیقاً به همان pathهایی بفرستید که در این داکیومنت آمده‌اند.

احراز هویت

هر درخواست باید هدر Authorization: Bearer sk-hoosha-… را داشته باشد. کلیدها در کنسول برنامه‌نویسان هوشا ساخته و باطل می‌شوند و هر کلید فقط یک بار، هنگام ساخت، نمایش داده می‌شود.

روال async

همه اندپوینت‌های تولید async هستند و رفتار یکسانی دارند:

1. درخواست POST به‌محض پذیرفته شدن تسک و کسر اعتبار، پاسخ 202 را همراه با یک id برمی‌گرداند. در این لحظه هنوز چیزی ساخته نشده است.
2. درخواست GET /generations/{id}/ ابتدا processing و سپس succeeded یا failed برمی‌گرداند.
3. در وضعیت succeeded، فیلد output نتایج را در خود دارد. در وضعیت failed، فیلد failure_reason علت را توضیح می‌دهد و اعتبار کمی بعد به‌طور خودکار بازگردانده می‌شود؛ پس از انجام بازگشت اعتبار، مقدار آن در credits_refunded نمایش داده می‌شود.

هر ۱-۲ ثانیه یک بار وضعیت را بررسی کنید. تصویرها در چند ثانیه و ویدیوها در چند دقیقه آماده می‌شوند. درخواست‌های GET از سهمیه شما کم نمی‌کنند، پس حتی یک حلقه طولانی بررسی وضعیت هم چیزی از سهمیه‌تان مصرف نمی‌کند.

اعتبار

اعتبار هنگام پذیرفته شدن تسک کسر می‌شود، نه هنگام پایان آن؛ بنابراین credits_charged در پاسخ 202 بیشترین هزینه‌ای است که این تولید می‌تواند داشته باشد، به‌جز یک استثنا که در آخرین مورد زیر آمده است. در این حالت‌ها بخشی از آن به‌طور خودکار بازمی‌گردد:

• در مدل‌های ویدیویی که ثانیه‌ای محاسبه می‌شوند (kling3، grok-imagine، seedance2، seedance25، kling-motion، lipsync)، اگر ویدیوی تحویلی دست‌کم 2 ثانیه کوتاه‌تر از مدت محاسبه‌شده باشد، اعتبار ثانیه‌های تحویل‌نشده بازگردانده می‌شود.
• هزینه seedance25 در حالت edit یا extend پس از تحویل ویدیو تسویه می‌شود؛ جزئیات در بخش «مدل‌های ویدیو» آمده است.
• سطح‌های high، xhigh و max در مدل‌های chatgpt-image-2.5-* یک تخمین را رزرو می‌کنند و پس از تحویل تصویر با هزینه واقعی تسویه می‌شوند. معمولاً مابه‌التفاوت برمی‌گردد؛ با یک پرامپت خیلی طولانی هزینه ممکن است کمی از رزرو بیشتر شود و باقی آن از موجودی شما کسر می‌شود، بدون اینکه در credits_refunded دیده شود.

اعتبار تولیدی که در سمت پرووایدر شکست بخورد به‌طور خودکار بازگردانده می‌شود؛ پس هرگز بابت نتیجه failed هزینه‌ای نمی‌پردازید. اندپوینت GET /models/ قیمت هر ترکیب مدل و پارامتری را که قابل فهرست کردن باشد برمی‌گرداند و جدول‌های این داکیومنت هم از همان منبع ساخته می‌شوند. حالت‌هایی که در این فهرست نمی‌گنجند در بخش «مدل‌های ویدیو» توضیح داده شده‌اند.

در /videos/، هر مقدار duration، quality، aspect_ratio، model_level یا هر گزینه مخصوص مدل که خارج از مجموعه مقادیر آن مدل در GET /models/ باشد، پیش از کسر هرگونه اعتبار با خطای 400 invalid_request رد می‌شود؛ این خطا نام فیلد و مقادیر مجاز را اعلام می‌کند. اندپوینت /images/ فیلدهای خود را به روشی بررسی می‌کند که در بخش «مدل‌های تصویر» آمده است. اگر duration، quality یا aspect_ratio را نفرستید، مقدار پیش‌فرض مدل به کار می‌رود.

محدودیت‌های طول پرامپت و سبک بر اساس code unitهای UTF-16 شمرده می‌شوند؛ بنابراین هر ایموجی دو کاراکتر حساب می‌شود.

مدل‌های تصویر

فیلدهای مشترک: model، prompt، aspect_ratio، quality در مدل‌های دارای سطح‌بندی کیفیت، level و background در مدل‌های chatgpt-image-2.5-*، output_format در nano-banana-2-pro و در صورت نیاز تصویرهای ورودی برای ویرایش.

مدل	نام	اعتبار	حداکثر پرامپت	تصاویر ورودی	کیفیت‌ها
nano-banana-2-1	Nano Banana 2.1	8 / 11 / 20	20,000	10	1K / 2K / 4K
nano-banana-2-pro	Nano Banana 2	9 / 11 / 14	20,000	14	1K / 2K / 4K
chatgpt-image-2.5-flare	ChatGPT Image 2.5 Flare	9 / 9 / 13	20,000	16	1K / 2K / 4K
chatgpt-image-2.5-sunburst	ChatGPT Image 2.5 Sunburst	9 / 9 / 13	20,000	16	1K / 2K / 4K
grok-imagine-2	Grok Imagine 2	4	8,000	5	—
chatgpt-image-2.0	ChatGPT Image 2.0	9 / 9 / 14	20,000	16	1K / 2K / 4K
hoosha-v1	Hoosha V1	5	20,000	5	—
chatgpt-image-1.5	ChatGPT Image 1.5	8	3,000	16	—
flux_kontext	Flux Kontext	8	3,000	1	—
seedream4	SeeDream 4.5	8	3,000	10	—

اعتبار به‌ازای هر تصویر محاسبه می‌شود. nano-banana-2-1 به‌ازای هر تصویر ورودی 0.3 اعتبار اضافه می‌کند و جمع را به عدد صحیح بالاتر گرد می‌کند. پیش‌فرض aspect_ratio برابر 4:3 است، به‌جز در chatgpt-image-2.0، مدل‌های chatgpt-image-2.5-* و nano-banana-2-1 (auto) و در chatgpt-image-1.5 و grok-imagine-2 (1:1). پیش‌فرض quality در مدل‌های سطح‌بندی‌شده 2K است (در nano-banana-2-1 برابر 1K) و بقیه مدل‌ها آن را نادیده می‌گیرند؛ در مدل سطح‌بندی‌شده، هر مقداری جز 1K، 2K یا 4K با خطای invalid_quality رد می‌شود.

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

محدودیت‌های chatgpt-image-2.0 که پیش از کسر اعتبار بررسی می‌شوند: این مدل نسبت‌های auto، 1:1، 2:3، 3:2، 3:4، 4:3، 4:5، 5:4، 9:16، 16:9، 1:2، 2:1، 1:3، 3:1، 9:21 و 21:9 را می‌پذیرد. auto و نسبت‌های 5:4، 4:5، 3:1، 1:3 و 9:21 فقط با کیفیت 1K ساخته می‌شوند (و اگر quality را نفرستید، پیش‌فرضشان 1K است) و سقف کیفیت 1:1 هم 2K است. درخواست کیفیتی بالاتر از حد مجاز آن نسبت با خطای unsupported_quality_for_aspect_ratio رد می‌شود. مدل chatgpt-image-1.5 فقط 1:1، 2:3 و 3:2 را می‌پذیرد.

chatgpt-image-2.5-flare و chatgpt-image-2.5-sunburst نسبت‌های auto، 1:1، 3:2، 2:3، 4:3، 3:4، 16:9، 9:16، 21:9، 27:16، 16:27، 9:8 و 8:9 را می‌پذیرند. auto فقط با کیفیت 1K ساخته می‌شود و اگر quality را نفرستید، پیش‌فرضش 1K است. level میزان تلاش مدل برای ساخت تصویر را تعیین می‌کند: low و medium (پیش‌فرض) با قیمت جدول محاسبه می‌شوند. high، xhigh و max به یک aspect_ratio مشخص نیاز دارند (وگرنه unsupported_aspect_ratio_for_level) و فقط با 2K یا 4K ساخته می‌شوند (وگرنه unsupported_quality_for_level). در این سه سطح، اعتبار جدول زیر به‌علاوه 3 اعتبار برای هر تصویر ورودی هنگام پذیرفته شدن درخواست رزرو می‌شود و پس از تحویل تصویر با هزینه واقعی تسویه می‌شود.

نسبت تصویر	high 2K	high 4K	xhigh 2K	xhigh 4K	max 2K	max 4K
1:1	21	34	36	59	80	133
3:2	11	23	19	40	42	89
2:3	11	23	19	40	42	89
4:3	13	25	23	44	50	99
3:4	13	25	23	44	50	99
16:9	9	19	15	34	32	75
9:16	9	19	15	34	32	75
21:9	6	13	10	21	22	46
27:16	9	20	16	35	35	79
16:27	9	20	16	35	35	79
9:8	17	30	30	53	67	117
8:9	17	30	30	53	67	117

background در این دو مدل و در همه سطح‌ها auto، opaque یا transparent است؛ هر مقدار دیگری با خطای invalid_background و level خارج از این پنج مقدار با خطای invalid_level رد می‌شود.

grok-imagine-2 نسبت‌های auto، 1:1، 2:3، 3:2، 16:9 و 9:16 را می‌پذیرد. auto از تصویر ورودی پیروی می‌کند، پس auto بدون تصویر ورودی با خطای invalid_aspect_ratio رد می‌شود. خروجی nano-banana-2-1 همیشه JPEG است.

فیلد output_format (فقط در nano-banana-2-pro) می‌تواند png (پیش‌فرض) یا jpg باشد؛ jpeg همان jpg در نظر گرفته می‌شود و هر مقدار دیگری با خطای invalid_output_format رد می‌شود.

مدل‌های ویدیو

فیلدهای مشترک: model، prompt، duration بر حسب ثانیه، quality، aspect_ratio و فیلدهای مخصوص هر مدل که در body درخواست داکیومنت شده‌اند. مقادیر duration، quality و model_level را به‌صورت string JSON بفرستید ("10"، نه 10). مقدار عددی در validation پذیرفته می‌شود، اما چند مدل سپس مقدار دیگری را جایگزین آن می‌کنند: duration: 10 در kling ویدیوی 5 ثانیه‌ای می‌سازد.

مدل	نام	اعتبار	مدت	کیفیت‌ها	سطح‌ها	صدا
grok-imagine	Grok Imagine 1.5	6–75	3–15 ثانیه	480 / 720 / 1080	—	بله
kling3	Kling 3.0 Turbo	33–210	3–15 ثانیه	720 / 1080	—	بله
seedance25	Seedance 2.5	68–2820	4–30 ثانیه	480 / 720 / 1080	—	بله
seedance2	Seedance 2	28–1980	4–15 ثانیه	480 / 720 / 1080 / 4k	pro / mini / fast	بله
kling-motion	Kling Motion	35–80	از ورودی	720 / 1080	2.6 / 3.0	بله
genjutsu	Genjutsu	70–555	از ورودی	480 / 720 / 1080	standard / lite	بله
gemini-omni-video	Google Omni	60–130	4 / 6 / 8 / 10 ثانیه	720 / 1080 / 4k	—	بله
veo3	Veo 3.1	30	8 ثانیه	720	—	بله
runway	Runway	15–30	5 / 10 ثانیه	720 / 1080	—	خیر
kling	Kling 2.5 Turbo	40–80	5 / 10 ثانیه	1080	—	خیر
seedance	Seedance v1	20–100	5 / 10 ثانیه	720 / 1080	—	خیر
lipsync	Lipsync	65–100	از ورودی	auto	v2-pro / v3	بله

مقادیر duration، quality و aspect_ratio باید از مجموعه داکیومنت‌شده همان مدل باشند؛ هر مقدار دیگری پیش از کسر اعتبار رد می‌شود. اگر فیلدی را نفرستید، پیش‌فرض مدل طبق GET /models/ به کار می‌رود. در جاهایی که کاتالوگ پیش‌فرضی اعلام نمی‌کند، kling3 از 5 ثانیه با کیفیت 720 و gemini-omni-video از 8 ثانیه با کیفیت 720 استفاده می‌کند.

در مدل‌هایی که ثانیه‌ای محاسبه می‌شوند، هزینه مدت درخواستی از همان ابتدا کسر می‌شود. اما kling-motion، genjutsu و lipsync مدت را از ورودی می‌گیرند: از ویدیوی رفرنس، یا در lipsync از مدت خروجی که در توضیح sync_mode آمده است. در جدول قیمت GET /models/ قیمت این سه مدل برای یک خروجی فرضی 5 ثانیه‌ای درج شده و هزینه واقعی به نسبت تعداد ثانیه‌ها محاسبه می‌شود. مدل‌های Seedance ویدیوهای ورودی را هم جزو ثانیه‌های قابل محاسبه حساب می‌کنند: طول ویدیوی رفرنس به مدت محاسبه‌شده اضافه می‌شود. در seedance25 وجود ویدیوی ورودی همچنین نرخ همه ثانیه‌ها را به نرخ پایین‌تر «با ویدیو» تغییر می‌دهد (به‌ترتیب 11، 23 و 57 اعتبار در کیفیت‌های 480، 720 و 1080، به‌جای 17، 38 و 94). مدل gemini-omni-video با ورودی video1 خودش مدت خروجی را تعیین می‌کند و برای آن مبلغ ثابت 110، 110 و 155 اعتبار، به‌ترتیب در کیفیت‌های 720، 1080 و 4k، کسر می‌شود؛ این قیمت در جدول GET /models/ نیامده است.

حالت‌های edit و extend در seedance25 با نرخ «با ویدیو» محاسبه می‌شوند:

• در edit مدت خروجی را مدل تعیین می‌کند؛ به همین دلیل اعتبار به اندازه دو برابر ثانیه‌های ورودی به‌علاوه 3 ثانیه رزرو می‌شود.
• در extend هزینه ثانیه‌های ورودی به‌علاوه duration درخواستی کسر می‌شود.

هر دو حالت پس از تحویل ویدیو تسویه می‌شوند: هزینه به ثانیه‌های ورودی به‌علاوه ثانیه‌های تحویل‌شده کاهش می‌یابد و مابه‌التفاوت بازگردانده می‌شود. هزینه هرگز افزایش نمی‌یابد.

با aspect_ratio: image، در مدل‌هایی که از آن پشتیبانی می‌کنند، نسبت تصویر خروجی از تصویر ورودی پیروی می‌کند.

مدل‌های موسیقی

مدل	نام	اعتبار	حداکثر پرامپت (ساده)	حداکثر پرامپت (سفارشی)	حداکثر سبک
suno-v6	Suno V6	15	3,000	5,000	1,000

دو حالت وجود دارد. حالت ساده (customMode: false، پیش‌فرض) یک توضیح کوتاه می‌گیرد و انتخاب بقیه موارد را به مدل می‌سپارد. حالت سفارشی (customMode: true) پرامپتی بلندتر را به‌عنوان متن ترانه، به‌همراه style و title می‌گیرد. هر درخواست با یک قیمت، دو ترک برمی‌گرداند.

مدل‌های گفتار

هزینه بر اساس طول کل متن دیالوگ محاسبه می‌شود: نرخ هر 1,000 کاراکتر در تعداد کاراکترها ضرب و بر 1,000 تقسیم می‌شود و حاصل در هر درخواست یک بار به عدد صحیح بالاتر گرد می‌شود. شمارش پس از حذف فاصله‌های ابتدا و انتهای هر خط انجام می‌شود و تگ‌های صوتی را هم در بر می‌گیرد. با نرخ 12 اعتبار برای هر 1,000 کاراکتر، هزینه 300 کاراکتر 4 اعتبار است.

مدل	نام	اعتبار / 1,000 کاراکتر	حداکثر خط	کل کاراکترها	حداکثر صدای متمایز
eleven-dialogue-v4	ElevenLabs v4	12	6	5–5,000	10
eleven-dialogue-v4-turbo	ElevenLabs v4 Turbo	6	6	5–5,000	10
eleven-dialogue-v3	ElevenLabs v3	12	6	5–5,000	10

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

صداها

نام	شخصیت	جنسیت	آیدی
شایان	گوینده	مرد	EkK5I93UQWFDigLMpZcX
غزاله	صدای زنانه و صمیمی	زن	5l5f8iK3YPeGga21rQIX
لئو	صدای بم و مقتدر	مرد	scOwDtmlUjD3prqpp97I
الی	گوینده	زن	Z3R5wn05IrDiVCyEkUrK
سهند	صدای رسا و خوش‌بیان	مرد	NNl6r8mD7vthiJatiJt1
سینا	صدای صمیمی و راحت	مرد	1SM7GgM6IMuvQlz2BwM3
آروین	صدای پخته و صمیمی	مرد	NOpBlnGInO9m6vDvFkFC
هلیا	صدای جوان و پرانرژی	زن	BZgkqPqms7Kj9ulSkVzn
پارسا	صدای جوان و شیک	مرد	IRHApOXLvnW57QJPQH2P
کاوه	گوینده	مرد	ZthjuvLPty3kTMaNKVKb
لیلی	صدای آهسته و نجواگونه	زن	uTwXcxvoi6bVu6ejzt6B
آوا	صدای شاد و پرانرژی	زن	kPzsL2i3teMYv0FxEYQ6
نیما	صدایی طبیعی و روان	مرد	UgBBYS2sOqTuMpoF3BR0
ترانه	صدای زنانه، پرکاریزما و نجواگونه	زن	BpjGufoPiobT79j2vtj4
بهرام	صدای عمیق و آرامش‌بخش	مرد	nPczCjzI2devNBz1zQrb
دلسا	صدای دخترانه و پرهیجان	زن	uYXf8XasLslADfZ2MB4u
سارا	صدای شفاف و قاطع	زن	56AoDkrOh6qfVPDXZ7Pt
فربد	صدای گرم و مثبت	مرد	Sq93GQT4X1lKDXsQcixO
لادن	صدای مرموز و باوقار	زن	flHkNRp1BlvT73UL6gyz
روژین	صدای نرم و گیرا	زن	wJqPPQ618aTW29mptyoc
اردشیر	صدای عمیق و سنگین	مرد	EiNlNiXeDU1pqqOPrYMO
داریوش	صدای بم و صمیمی	مرد	6F5Zhi321D3Oq7v1oNT4
رومینا	صدای جذاب و بازیگوش	زن	eVItLK1UvXctxuaRV2Oq
بنیامین	صدای عمیق و تسکین‌دهنده	مرد	LruHrtVF6PSyGItzMNHS
نیایش	صدایی ملایم و آرامش‌بخش	زن	1wGbFxmAM3Fgw63G1zZJ
سهراب	صدای آرام و متین	مرد	hqfrgApggtO1785R4Fsn
روزبه	صدای گرم و آرامش‌بخش	مرد	MJ0RnG71ty4LH3dvNfSd
لونا	صدای دختر بچه شاد و بازیگوش	زن	ocZQ262SsZb9RIxcQBOj
شهرزاد	گوینده	زن	ndcUYGFbbd96WXiZVVaQ
ننه جون	صدای مادربزرگ مهربان	زن	0rEo3eAjssGDUCXHYENf

اندپوینت GET /models/ همین صداها را در فیلد voices مدل گفتار، در کنار زبان‌های پذیرفته‌شده در languages، برمی‌گرداند.

Idempotency

برای اینکه بتوانید ارسال یک درخواست را بی‌خطر تکرار کنید، هدر Idempotency-Key (یا فیلد client_request_id در body) را بفرستید. اگر هر دو را بفرستید، هدر اولویت دارد و کلیدی که بیش از 200 کاراکتر باشد به 200 کاراکتر اولش کوتاه می‌شود. کلید همراه با پرامپت درخواست (در گفتار، دیالوگ آن) هویت درخواست را تعیین می‌کند؛ پس همان کلید با پرامپتی متفاوت، درخواست دیگری به حساب می‌آید. هیچ فیلد دیگری مقایسه نمی‌شود: همان کلید و پرامپت با مدل یا پارامترهای متفاوت، پاسخ درخواست اول را دوباره برمی‌گرداند.

• تکرار درخواست ظرف 15 دقیقه پس از پذیرفته شدن درخواست اول، همان body اصلی را با وضعیت 200 به‌جای 202 برمی‌گرداند و دوباره اعتباری کسر نمی‌شود.
• تکرار درخواست در حالی که درخواست اول هنوز در حال پردازش است، 409 request_in_progress برمی‌گرداند. کمی بعد دوباره تلاش کنید.
• درخواست ردشده ذخیره نمی‌شود؛ پس تلاش دوباره با همان کلید، آن را از نو اجرا می‌کند.
• پس از خطای 503 provider_unavailable با کلید جدید دوباره تلاش کنید. اگر همان کلید را بفرستید، در /images/، /music/ و /speech/ تا 60 ثانیه پاسخ 409 می‌گیرید و در /videos/ پاسخ 202 مربوط به همان تولید ناموفق.
• در /videos/ فقط درخواست‌های بدون آیدی آپلود قابل تکرارند. تکرار درخواستی که از آیدی آپلود استفاده کرده با خطای 400 invalid_request رد می‌شود، چون درخواست اول آن آیدی‌ها را مصرف کرده است.
• موجودی پیش از تکرار بررسی می‌شود: در /images/ اگر موجودی شما صفر شده باشد و در /videos/ اگر کمتر از قیمت باشد، تکرار با 402 پاسخ داده می‌شود.

Rate limit

فقط درخواست‌های نوشتنی شمرده می‌شوند: هر POST به اندپوینت‌های تولید، حتی آن‌هایی که به‌خاطر ورودی نامعتبر رد می‌شوند، از سهمیه دقیقه‌ای حساب شما کم می‌کند. این سهمیه را GET /credits/ در فیلد rate_limit_per_minute برمی‌گرداند (پیش‌فرض 10). آپلودها سقف جداگانه‌ای دارند: 10,000 آپلود در هر 24 ساعت. درخواست‌های GET از سهمیه شما کم نمی‌کنند.

پاسخ درخواستی که محدود شده باشد 429 rate_limit_exceeded است؛ تعداد ثانیه‌های انتظار در فیلد retry_after body خطا و همان مقدار در هدر Retry-After می‌آید. مسدودسازی احراز هویت هم با 429 rate_limit_exceeded پاسخ می‌دهد، اما بدون هیچ‌کدام از این دو.

ورودی‌های مدیا

اندپوینت‌هایی که مدیای ورودی می‌پذیرند، آن را به سه روش دریافت می‌کنند و می‌توانید این روش‌ها را با هم ترکیب کنید. /images/ و /videos/ آیدی‌های آپلود را از فیلدهای متفاوتی می‌خوانند. فیلدی که اندپوینت نمی‌خواند نادیده گرفته می‌شود و تسک بدون آن ورودی اجرا می‌شود.

روش	/images/	/videos/	توضیحات
URL هاست‌شده	image_urls (قابل تکرار)	image_urls (قابل تکرار)	باید https:// باشد و خارج از هوشا هاست شود. فقط برای تصویر.
آیدی آپلود	uploads (آرایه)	فیلدهای شماره‌دار image1…imageN، video1…videoN، audio1…audioN	آیدی‌های دریافتی از POST /uploads/. یک‌بارمصرف. حدود 20 دقیقه پس از آپلود منقضی می‌شوند.
فایل مستقیم	بخش‌های multipart با نام image1…imageN	بخش‌های multipart با نام image1…imageN	درخواست را به‌صورت multipart/form-data بفرستید.

در /images/، فیلد شماره‌دار image1 فقط به‌صورت بخش فایل خوانده می‌شود؛ پس آیدی آپلودی که در آن بفرستید نادیده گرفته می‌شود. در /videos/ فیلد uploads نادیده گرفته می‌شود و آیدی آپلود باید به شکل کامل 36 کاراکتری باشد.

فیلدهای شماره‌دار برای مدل‌هایی مهم‌اند که ترتیب ورودی‌ها برایشان معنا دارد: first-frame-last-frame از image1 به‌عنوان فریم اول و از image2 به‌عنوان فریم آخر استفاده می‌کند. URLهای هاست‌شده در image_urls به‌ترتیب، کم‌شماره‌ترین جایگاه‌های خالی imageN را پر می‌کنند. همه اندپوینت‌ها به‌جز /speech/ علاوه بر JSON، multipart/form-data را هم می‌پذیرند. /speech/ برای آرایه dialogue به JSON نیاز دارد و برای ارسال مستقیم فایل باید از multipart استفاده کنید، چون JSON نمی‌تواند فایل خام را منتقل کند.

پذیرش فایل مستقیم در هر اندپوینت متفاوت است. /images/ فرمت‌های png، jpg، jpeg، webp، gif، bmp، tiff، tif، heic و heif را می‌پذیرد، همه را به‌جز PNG و JPEG به JPEG تبدیل می‌کند و بخش‌هایی را که از سقف تصویر ورودی مدل بیشتر باشند نادیده می‌گیرد. /videos/ فرمت‌های png، jpg، jpeg، webp و gif را تا حجم 10 مگابایت برای هر فایل می‌پذیرد.

اندپوینت POST /uploads/ این فایل‌ها را می‌پذیرد:

نوع	پسوندها	حداکثر حجم	مدت
تصویر	png jpg jpeg webp gif bmp tiff tif heic heif	30 مگابایت	—
ویدیو	mp4 mov webm m4v	200 مگابایت	حداکثر 30 ثانیه
صوت	mp3 wav m4a	15 مگابایت	2 تا 30 ثانیه

تصویرها و ویدیوها با decode کردن خود فایل validate می‌شوند، نه با اتکا به پسوند آن، و هر تصویر با فرمتی ذخیره می‌شود که محتوایش نشان می‌دهد. مدت فایل صوتی در صورتی بررسی می‌شود که فایل قابل خواندن باشد. تصویرهای gif، bmp، tiff، webp، heic و heif به JPEG تبدیل می‌شوند، ابعاد تصویرهای PNG و JPEG که ضلع بلندشان بیش از 4,096 پیکسل باشد کوچک می‌شود و فایل صوتی m4a به MP3 تبدیل می‌شود؛ بنابراین فایل ذخیره‌شده ممکن است با فایلی که فرستاده‌اید متفاوت باشد.

آیدی آپلود یک‌بارمصرف است و حدود 20 دقیقه پس از ساخته شدن منقضی می‌شود؛ پس تولیدی را که از آن استفاده می‌کند در همین بازه ارسال کنید. وقتی درخواستی آیدی‌ای را به کار بگیرد، رفرنس‌های بعدی به آن شکست می‌خورند، حتی اگر همان درخواست بعداً رد شود (مثلاً به‌خاطر اعتبار، تعداد تصویرها یا یکی از قواعد ورودی). پیش از تلاش دوباره برای درخواست ردشده، فایل را دوباره آپلود کنید. آپلودهای استفاده‌نشده هر حساب، از جمله آپلودهای اپ هوشا، در یک مجموعه نگه داشته می‌شوند: هر POST /uploads/ قدیمی‌ترین آپلودهای استفاده‌نشده بیش از 1,000 را حذف می‌کند و هر آپلود در اپ هوشا این مجموعه را به 55 آپلود جدیدتر کاهش می‌دهد.

خطاها

خطاهایی که API برمی‌گرداند همگی یک فرمت یکسان دارند:

کد
{ "error": { "code": "insufficient_credits", "message": "This request costs 26 credits.", "required_credits": 26 } }

مقدار code پایدار است و می‌توانید با خیال راحت منطق برنامه را بر اساس آن بنویسید؛ message متنی انگلیسی است و ممکن است تغییر کند. برخی کدها فیلدهای اضافه‌ای دارند که در جدول زیر آمده‌اند.

وضعیت HTTP	code	فیلدهای اضافه
400	invalid_request, bad_request, invalid_model, prompt_required, prompt_too_long, invalid_quality, invalid_aspect_ratio, unsupported_quality_for_aspect_ratio, invalid_level, invalid_background, unsupported_aspect_ratio_for_level, unsupported_quality_for_level, invalid_output_format, style_too_long, dialogue_required, too_many_lines, invalid_line_format, empty_line, no_speakable_text, invalid_voice, too_many_voices, text_too_short, text_too_long, invalid_stability, invalid_language, invalid_image_url, invalid_upload, too_many_images, invalid_file, unsupported_image_format, image_processing_failed, pricing_unavailable	—
401	unauthorized	—
402	insufficient_credits	required_credits، به‌جز در /videos/ و در /images/ وقتی موجودی صفر است
404	not_found	—
405	method_not_allowed	—
409	request_in_progress	—
415	unsupported_media_type	—
429	rate_limit_exceeded	retry_after، به‌جز در مسدودسازی احراز هویت
500	invalid_file (POST /uploads/ نتوانست فایل را ذخیره کند)	—
503	provider_unavailable	id (تصویر، موسیقی، گفتار)

خطای bad_request یعنی body درخواست به‌صورت JSON یا multipart parse نشد.

لینک‌های خروجی

لینک‌های نتیجه signed هستند و دست‌کم 24 ساعت معتبرند. برای گرفتن لینک‌های تازه، وضعیت تولید را دوباره بررسی کنید. خود فایل‌های مدیا 90 روز نگه داشته می‌شوند؛ پس از آن output خالی است، به‌جز آیتم‌های موسیقی که title و duration را نگه می‌دارند و url و cover_image آن‌ها null می‌شود.