Video API؛ تولید ویدیو و همگامسازی لب با کار پسزمینه و کلید API
تولید ویدیو چند دقیقه طول میکشد، پس مسیرهای POST /v1/videos و POST /v1/lipsync در وان ای آی (1ai) همیشه به صورت کار پسزمینه اجرا میشوند: پاسخ 202 با یک شناسهی job_ میگیرید، وضعیت را میپرسید و بعد فایل را برمیدارید. اعتبار پیش از اجرا رزرو میشود و اگر کار شکست بخورد یا لغو شود، برمیگردد. این کارها و فایلهایشان در استودیو و گالری حساب شما دیده نمیشوند. استودیوی «ترندساز» از این API در دسترس نیست.
چرا با 1ai
کار پسزمینه
درخواست فوراً با 202 و یک شناسه جواب میگیرد؛ لازم نیست اتصال را چند دقیقه باز نگه دارید.
از روی توصیف یا تصویر
توصیف متنی را بفرستید و در صورت نیاز تصویر مرجع را در input_reference بگذارید.
همگامسازی لب
یک عکس یا ویدیو و یک فایل صوتی WAV یا MP3 بفرستید. طول صدا را 1ai خودش اندازه میگیرد.
شکست و لغو بدون هزینه
اعتبار پیش از اجرا رزرو میشود. اگر کار شکست بخورد یا لغو شود، اعتبار رزروشده برمیگردد.
در چند قدم
- ۱
کلید API بسازید
از بخش توسعهدهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.
- ۲
کار را بسازید
مدل و توصیف را به https://1ai.ir/v1/videos بفرستید و id را از پاسخ 202 بردارید.
- ۳
وضعیت را بپرسید
GET /v1/videos/{id} را با فاصله صدا بزنید تا status برابر completed یا failed شود.
- ۴
فایل را بردارید
GET /v1/videos/{id}/content به یک لینک امضاشده هدایت میکند؛ در curl پرچم -L را بگذارید.
مدلهای ویدیو در API
همهی مدلهاGrok Imagine Video 1.5 Lite
سریعترین و ارزانترین ویدیوساز
Grok Imagine Video 1.5
ویدیوی پرجزئیات تا ۱۰۸۰p از گراک
نمونه درخواست با curl
curl https://1ai.ir/v1/videos \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling/kling-v3.0-std",
"prompt": "A red apple slowly rotating on a white table",
"seconds": 5,
"size": "1280x720"
}'پاسخ 202 همان شیء کار است:
{
"id": "job_…",
"object": "video",
"model": "kling/kling-v3.0-std",
"status": "queued",
"progress": 0,
"created_at": 1793923200,
"completed_at": null,
"prompt": "A red apple slowly rotating on a white table",
"seconds": "5",
"aspect_ratio": "16:9",
"resolution": "720p",
"estimated_credits": …,
"credits": …,
"output": null,
"error": null
}شناسهی مدل را از فهرست همین صفحه بردارید.
وضعیت، دریافت فایل، لغو
# Status
curl https://1ai.ir/v1/videos/job_... -H "Authorization: Bearer $ONEAI_API_KEY"
# Download when completed (follows the redirect)
curl -L -o result.mp4 https://1ai.ir/v1/videos/job_.../content -H "Authorization: Bearer $ONEAI_API_KEY"
# Cancel a running job, or delete a finished job's files
curl -X DELETE https://1ai.ir/v1/videos/job_... -H "Authorization: Bearer $ONEAI_API_KEY"status | معنی |
|---|---|
queued | در صف |
in_progress | در حال اجرا |
completed | تمام شده؛ output پر است و فایل آماده است |
failed | شکست خورده؛ علت در error است |
cancelled | لغو شده |
- دریافت فایل به یک لینک امضاشده هدایت میکند (302) که یک ساعت اعتبار دارد؛ برای لینک تازه همین مسیر را دوباره صدا بزنید.
DELETEکار در حال اجرا را لغو میکند و اعتبار رزروشده را برمیگرداند. روی کار تمامشده فایلها را حذف میکند و شیء کار باoutput: nullمیماند.
نمونه کامل با Python
# pip install requests
import os, time, requests
API = "https://1ai.ir/v1/videos"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"}
job = requests.post(API, headers=HEADERS, json={
"model": "kling/kling-v3.0-std",
"prompt": "A red apple slowly rotating on a white table",
"seconds": 5,
}, timeout=120).json()
while job["status"] in ("queued", "in_progress"):
time.sleep(15)
job = requests.get(f"{API}/{job['id']}", headers=HEADERS, timeout=60).json()
if job["status"] != "completed":
raise SystemExit(job["error"])
res = requests.get(f"{API}/{job['id']}/content", headers=HEADERS, timeout=600)
open("result.mp4", "wb").write(res.content)فیلدهای درخواست ویدیو
بدنه JSON است یا multipart.
| فیلد | نوع | توضیح |
|---|---|---|
model | رشته | شناسهی مدل ویدیو |
prompt | رشته | توصیف ویدیو |
negative_prompt | رشته، اختیاری | چیزی که نباید در ویدیو باشد |
seconds | عدد یا رشته، اختیاری | طول ویدیو؛ پیشفرض اولین طولی است که مدل میپذیرد |
size | رشته، اختیاری | مثل 1280x720؛ به نسبت تصویر و کیفیت تبدیل میشود |
aspect_ratio و resolution | رشته، اختیاری | به جای size؛ هر دو با هم نیایند |
input_reference | فایل، اختیاری | تصویر مرجع: نشانی، data URL، { "image_url": "…" } یا فایل multipart |
هر مدل طولها و نسبتهای خودش را دارد و بقیه را رد میکند؛ چون هزینهی کار به ثانیههایی بستگی دارد که میخواهید.
همگامسازی لب با POST /v1/lipsync
curl https://1ai.ir/v1/lipsync \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-F model=heygen/avatar-iv \
-F image=@face.jpg \
-F audio=@voice.mp3- یکی از
imageوvideoرا بفرستید، نه هر دو. بعضی مدلها فقط عکس چهره میپذیرند و ویدیو را رد میکنند. audioباید WAV یا MP3 باشد و حداکثر ۳۰۰ ثانیه. فرمتهای دیگر خطایaudio_unreadableو صدای بلندتر خطایaudio_too_longمیدهد.secondsنفرستید. 1ai طول صدا را خودش اندازه میگیرد و هزینه به اندازهی کوتاهترِ نتیجه و صدا حساب میشود.- وضعیت، دریافت فایل و لغو مثل ویدیو است:
GET /v1/lipsync/{id}،GET /v1/lipsync/{id}/contentوDELETE /v1/lipsync/{id}.
فایلهای ورودی
هر فایل ورودی میتواند یکی از این سه باشد:
- نشانی http(s): تا ۵۰ مگابایت. نشانیهای داخلی پذیرفته نمیشوند.
- data URL با base64 در بدنهی JSON.
- فایل multipart: تا ۲۵ مگابایت برای هر فایل.
نوع فایل از روی محتوایش تشخیص داده میشود، نه نام یا سرآیند آن. فایلهای ورودی وقتی کار تمام یا رد شود حذف میشوند.
خطاها
| کد | معنی |
|---|---|
402 insufficient_credits | اعتبار کافی نیست |
400 media_input_unsupported | طول، نسبت یا نوع ورودی برای این مدل مجاز نیست |
400 input_fetch_failed | فایل از نشانی دادهشده دریافت نشد |
400 model_kind_mismatch | این مدل برای این مسیر نیست |
404 job_not_found | کاری با این شناسه برای این حساب وجود ندارد |
409 job_not_ready | کار هنوز تمام نشده و فایلی ندارد |
404 content_not_found | فایل این کار حذف شده است |
اگر کاری شکست بخورد، علت در error.code میآید: media_input_refused، media_copyright_refused، provider_timeout، output_invalid، output_download_failed یا job_failed.
سوالات متداول
هزینهی ویدیو چطور حساب میشود؟
ویدیو به اندازهی ثانیههایی که میخواهید حساب میشود و قیمت هر مدل در صفحهی همان مدل است. پیش از اجرا اعتبار رزرو میشود؛ تخمین آن در estimated_credits و مبلغ نهایی در credits میآید.
اگر کار شکست بخورد اعتبارم کم میشود؟
خیر. اگر کار شکست بخورد یا پیش از پایان لغو شود، اعتبار رزروشده برمیگردد. حذف فایلهای کاری که تمام شده است، هزینهی آن را برنمیگرداند.
لینک فایل چقدر اعتبار دارد؟
یک ساعت. برای لینک تازه دوباره GET /v1/videos/{id}/content را صدا بزنید. کتابخانههایی که هدایت را دنبال میکنند فایل را مستقیم میگیرند.
کارهای API در استودیو یا گالری من دیده میشوند؟
خیر. کارهای API و فایلهایشان فقط از همین مسیرها در دسترساند و در استودیو و گالری حساب شما نمیآیند.
«ترندساز» هم از API در دسترس است؟
خیر. «ترندساز» فقط در استودیو کار میکند و مدلهایش در این مسیرها پذیرفته نمیشوند.
مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
چطور پروژهای را که با کتابخانهی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدلها و مدیریت خطا.

کلید API در 1ai: امنیت، محدودیتها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدلهای مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.
صفحههای مرتبط
همهی امکاناتMusic API
توصیف قطعه و در صورت نیاز متن ترانه را بفرستید، شناسهی کار را بگیرید و وقتی کار تمام شد فایل صوتی را بردارید.
OpenAI SDK
کتابخانهی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.
OCR API
یک PDF یا تصویر را با نشانی یا data URL بفرستید و متن هر صفحه را به صورت Markdown پس بگیرید؛ هزینه فقط به ازای صفحههایی است که واقعاً خوانده شدهاند.
Video API؛ تولید ویدیو و همگامسازی لب با کار پسزمینه و کلید API
توصیف یا تصویر مرجع را بفرستید، شناسهی کار را بگیرید و وقتی کار تمام شد فایل ویدیو را بردارید. همگامسازی لب هم با یک عکس یا ویدیو و یک فایل صوتی به همین روش کار میکند.
ساخت کلید API