رسانه: ساخت تصویر، ویدیو، صدا و موسیقی با API

مرور API رسانهٔ یوتاپن: ساخت تصویر، ویدیوی غیرهم‌زمان، تبدیل متن به گفتار و موسیقی؛ انتخاب خودکار مدل، لینک امضاشدهٔ فایل، نگهداری ۳۰ روزه و قیمت.

با همان کلید sk-up-… و همان base_url می‌توانی علاوه بر متن، تصویر و ویدیو و صدا و موسیقی هم بسازی. چهار مسیر داری:

کار	مسیر	پاسخ
ساخت تصویر	`POST /v1/images/generations`	هم‌زمان؛ لینک فایل یا `b64_json`
ساخت ویدیو	`POST /v1/videos`	غیرهم‌زمان؛ شناسهٔ کار، بعد پیگیری با `GET /v1/videos/{id}`
متن به گفتار	`POST /v1/audio/speech`	خود فایل صوتی (مثل OpenAI)
موسیقی	`POST /v1/audio/music`	هم‌زمان؛ لینک فایل

فهرست مدل‌ها و قیمت تومانی هر کدام در صفحهٔ مدل‌ها است. اگر نمی‌خواهی کد بنویسی، همهٔ این کارها در استودیو هم انجام می‌شود.

انتخاب خودکار مدل

فیلد model را خالی بگذار یا یکی از این شناسه‌ها را بفرست تا مناسب‌ترین مدل برای درخواستت انتخاب شود:

شناسه	برای
`uttapen/auto-image`	تصویر: عکس واقعی‌نما، محصول، انیمه، پوستر با متن، ویرایش عکس
`uttapen/auto-video`	ویدیو: متن به ویدیو، متحرک کردن عکس، پیش‌نویس ارزان
`uttapen/auto-music`	موسیقی: قطعهٔ کامل یا کوتاه
`uttapen/auto-speech`	گفتار: متن فارسی یا انگلیسی

یک مدل زبانی ارزان درخواستت را می‌خواند و از جدول ما مدل را برمی‌دارد. هزینهٔ همین تشخیص (معمولاً کسری از یک تومان) جدا حساب و در پاسخ در uttapen.classifier_cost_toman گزارش می‌شود؛ دلیل انتخاب هم در uttapen.auto می‌آید. اگر تشخیص به هر دلیلی کار نکند، قاعده‌های ثابت تصمیم می‌گیرند (مثلاً وقتی عکس فرستاده‌ای، مدل ویرایش انتخاب می‌شود) و برای تشخیص ناموفق پولی کم نمی‌شود. اگر خودت مدلی را نام ببری، همیشه همان اجرا می‌شود.

پرداخت

پیش از اجرا مبلغی موقت رزرو می‌شود: ویدیو بر اساس مدت × قیمت هر ثانیه برای رزولوشن و صدای انتخابی، تصویر بر اساس قیمت هر تصویر، گفتار بر اساس تعداد نویسه و موسیقی بر اساس قیمت هر قطعه.
بعد از ساخت، فقط هزینهٔ واقعی که سازندهٔ مدل گزارش می‌کند کم می‌شود و بقیهٔ رزرو برمی‌گردد. برای گفتار، چون هزینه در پاسخ نمی‌آید، قیمت منتشرشدهٔ مدل × تعداد نویسه حساب می‌شود.
ساخت ناموفق رایگان است: خطا، رد شدن به‌خاطر قوانین محتوا، تمام نشدن ویدیو در مهلت یا نرسیدن فایل، همه رزرو را کامل آزاد می‌کنند.
هدرهای X-Uttapen-Cost-Toman و X-Uttapen-Balance-Toman در پاسخ هم‌زمان می‌آیند؛ برای ویدیو cost_toman در شیء کار پس از تکمیل پر می‌شود.

فایل‌ها و نگهداری

خروجی‌ها روی سرور خودمان در ایران نگه داشته می‌شوند. هر url در پاسخ یک لینک امضاشده روی https://api.uttapen.ir/v1/files/… است که ۲۴ ساعت بدون کلید باز می‌شود؛ برای لینک تازه، شیء کار را دوباره بگیر:

curl https://api.uttapen.ir/v1/uttapen/media/<id> -H "Authorization: Bearer sk-up-..."

فایل‌ها ۳۰ روز نگه داشته می‌شوند و بعد پاک می‌شوند؛ اگر لازمشان داری دانلودشان کن. فهرست کارهای اخیرت: GET /v1/uttapen/media?kind=video&limit=20. متن درخواست‌هایی که از API می‌فرستی ذخیره نمی‌شود.

قوانین محتوا

محتوای جنسی، هر محتوای آسیب‌زا دربارهٔ کودکان، خشونت شدید و تصویر یا صدای ساخته‌شده شبیه افراد واقعی ساخته نمی‌شود. چنین درخواستی پیش از هر هزینه‌ای با 400 content_policy_violation و پیامی فارسی رد می‌شود. اگر خود سازندهٔ مدل درخواست را رد کند هم همین کد برمی‌گردد و چیزی کم نمی‌شود.

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

status	code	یعنی
400	`content_policy_violation`	محتوای ممنوع
400	`invalid_request`	پارامتر نامعتبر؛ `param` نام فیلد را می‌گوید (مثلاً مدت ویدیویی که مدل ندارد)
400	`model_not_available`	قیمت این مدل فعلاً قابل محاسبه نیست
402	`insufficient_balance`	موجودی برای رزرو کافی نیست
429	`too_many_active_jobs`	بیش از ۳ ساخت هم‌زمان
429	`rate_limit_exceeded`	سقف ساخت در دقیقه
503	`server_busy`	ظرفیت موقتاً پر است؛ `Retry-After` را رعایت کن

حداکثرها: ۴ تصویر در هر درخواست، متن درخواست ۴٬۰۰۰ نویسه (گفتار ۵٬۰۰۰)، ویدیو تا ۲۰ ثانیه، و حداکثر ۴ تصویر مرجع هرکدام تا ۱۰ مگابایت (آدرس https یا data:image/png|jpeg|webp;base64). کدهای عمومی در خطاها آمده‌اند.