راهنمای اتصال به API

Video API؛ تولید ویدیو و همگام‌سازی لب با کار پس‌زمینه و کلید API

تولید ویدیو چند دقیقه طول می‌کشد، پس مسیرهای POST /v1/videos و POST /v1/lipsync در وان ای آی (1ai) همیشه به صورت کار پس‌زمینه اجرا می‌شوند: پاسخ 202 با یک شناسه‌ی job_ می‌گیرید، وضعیت را می‌پرسید و بعد فایل را برمی‌دارید. اعتبار پیش از اجرا رزرو می‌شود و اگر کار شکست بخورد یا لغو شود، برمی‌گردد. این کارها و فایل‌هایشان در استودیو و گالری حساب شما دیده نمی‌شوند. استودیوی «ترندساز» از این API در دسترس نیست.

چرا با 1ai

کار پس‌زمینه

درخواست فوراً با 202 و یک شناسه جواب می‌گیرد؛ لازم نیست اتصال را چند دقیقه باز نگه دارید.

از روی توصیف یا تصویر

توصیف متنی را بفرستید و در صورت نیاز تصویر مرجع را در input_reference بگذارید.

همگام‌سازی لب

یک عکس یا ویدیو و یک فایل صوتی WAV یا MP3 بفرستید. طول صدا را 1ai خودش اندازه می‌گیرد.

شکست و لغو بدون هزینه

اعتبار پیش از اجرا رزرو می‌شود. اگر کار شکست بخورد یا لغو شود، اعتبار رزروشده برمی‌گردد.

در چند قدم

  1. ۱

    کلید API بسازید

    از بخش توسعه‌دهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.

  2. ۲

    کار را بسازید

    مدل و توصیف را به https://1ai.ir/v1/videos بفرستید و id را از پاسخ 202 بردارید.

  3. ۳

    وضعیت را بپرسید

    GET /v1/videos/{id} را با فاصله صدا بزنید تا status برابر completed یا failed شود.

  4. ۴

    فایل را بردارید

    GET /v1/videos/{id}/content به یک لینک امضاشده هدایت می‌کند؛ در curl پرچم -L را بگذارید.

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

همه‌ی مدل‌ها

Kling 3.0 Pro

کلینگ
ویدیو

ویدیوی سینمایی با حرکت طبیعی و صدا

۲۵٫۲ اعتبار / هر ثانیه ویدیو
API

Grok Imagine Video 1.5 Lite

ایکس‌ای‌آی
ویدیو

سریع‌ترین و ارزان‌ترین ویدیوساز

۳ اعتبار / هر ثانیه ویدیو (480p)
API
ویدیو

کیفیت کلینگ با هزینه‌ی کمتر

۱۸٫۹ اعتبار / هر ثانیه ویدیو
API

Kling O1

کلینگ
ویدیو

حرکت دقیق و یکدست از روی توصیف یا تصویر

۱۶٫۸ اعتبار / هر ثانیه ویدیو
API

Grok Imagine Video 1.5

ایکس‌ای‌آی
ویدیو

ویدیوی پرجزئیات تا ۱۰۸۰p از گراک

۱۲ اعتبار / هر ثانیه ویدیو (480p)
API

Wan 3.0

کوئن
ویدیو

ویدیو با صدا از علی‌بابا

۷٫۵ اعتبار / هر ثانیه ویدیو (480p)
API
ویدیو

بالاترین کیفیت خانواده‌ی وان

۱۰٫۲ اعتبار / هر ثانیه ویدیو (480p)
API
ویدیو

ویدیوی روان تا ۱۰۸۰p از علی‌بابا

۱۴٫۸۲ اعتبار / هر ثانیه ویدیو
API

Hailuo 3 Max

مینی‌مکس
ویدیو

حرکت روان و فیزیک واقع‌گرایانه

۷٫۵ اعتبار / هر ثانیه ویدیو (480p)
API

نمونه درخواست با curl

bash
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 همان شیء کار است:

json
{
  "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
}

شناسه‌ی مدل را از فهرست همین صفحه بردارید.

وضعیت، دریافت فایل، لغو

bash
# 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

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

bash
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
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

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

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

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

۴ دقیقه مطالعه
همه‌ی امکانات

Music API

توصیف قطعه و در صورت نیاز متن ترانه را بفرستید، شناسه‌ی کار را بگیرید و وقتی کار تمام شد فایل صوتی را بردارید.

OpenAI SDK

کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.

OCR API

یک PDF یا تصویر را با نشانی یا data URL بفرستید و متن هر صفحه را به صورت Markdown پس بگیرید؛ هزینه فقط به ازای صفحه‌هایی است که واقعاً خوانده شده‌اند.

Video API؛ تولید ویدیو و همگام‌سازی لب با کار پس‌زمینه و کلید API

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

ساخت کلید API