API و توسعه‌دهندگان

برای توسعه‌دهندگان

ویدئو را از دل کد خودتان اداره کنید

بارگذاری، انتشار، امبد و آمار تماشا — همان کارهایی که در داشبورد انجام می‌دهید، این بار از سمت سرور. یک کلید بسازید و شروع کنید.

ساخت کلید API OpenAPI 3.1 مستندات متنی برای هوش مصنوعی

شروع سریع

کلید را در Settings → کلیدهای API بسازید. کلید فقط یک بار نمایش داده می‌شود.

curl https://ttve.ir/api/v1/videos \
  -H "Authorization: Bearer ttve_live_..."

برای اطمینان از درست‌کارکردن کلید، GET /api/v1/me را صدا بزنید: فضای کاری، پلن، مصرف فعلی و دسترسی‌های همان کلید را برمی‌گرداند.

احراز هویت

یک کلید، یک فضای کاری

هر کلید به یک فضای کاری گره خورده است؛ به همین دلیل هیچ‌جای این API پارامتری به نام workspace وجود ندارد و هیچ کلیدی به فضای دیگری دسترسی ندارد.

کلید فقط سمت سرور

این API عمداً هدر CORS نمی‌فرستد. کلید را در کد سمت مرورگر نگذارید؛ هر بازدیدکننده می‌تواند آن را بخواند.

یک‌بار نمایش

فقط هش کلید ذخیره می‌شود. کلید گم‌شده بازیابی نمی‌شود؛ باطلش کنید و کلید تازه بسازید.

کلید کلید نمی‌سازد

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

دسترسی‌ها (scopes)

videos:readخواندن ویدئوها
videos:writeویرایش و حذف ویدئوها
uploads:writeبارگذاری ویدئوی جدید
collections:readخواندن مجموعه‌ها
collections:writeویرایش مجموعه‌ها
subtitles:writeمدیریت زیرنویس‌ها
analytics:readخواندن آمار

بارگذاری

سه مرحله، چون فایل از دل API عبور نمی‌کند

نشانی‌ای که در مرحلهٔ اول می‌گیرید متعلق به TTVE است، نه یک presigned URL از S3؛ به همان اندازه و همان نوع فایلی که اعلام کرده‌اید گره خورده و منقضی می‌شود.

رزرو جا و گرفتن نشانی

فضای باقی‌ماندهٔ پلن بررسی می‌شود و رکورد ویدئو ساخته می‌شود.

curl -X POST https://ttve.ir/api/v1/uploads \
  -H "Authorization: Bearer ttve_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"قسمت اول","filename":"ep1.mp4","contentType":"video/mp4","sizeBytes":184320000}'

ارسال فایل
کل فایل را با یک درخواست PUT به uploadUrl بفرستید و هدرهای برگشتی از مرحلهٔ اول را عیناً همراهش بگذارید.
3
پایان و ارسال به صف پردازش
حجم ذخیره‌شده و امضای فایل بررسی می‌شود، بعد ویدئو به صف تبدیل می‌رود. تکرار این درخواست بی‌خطر است و کار را دوبار در صف نمی‌گذارد.
```
curl -X POST https://ttve.ir/api/v1/uploads/{videoId}/complete \
  -H "Authorization: Bearer ttve_live_..."
```

بعد از آن، GET /api/v1/videos/{id} را تا رسیدن status به READY بررسی کنید. پردازش چند دقیقه طول می‌کشد و تا آماده‌نشدن ویدئو نمی‌توانید آن را عمومی کنید.

مرجع

فهرست endpointها

توضیح کامل هر کدام، همراه با شکل درخواست و پاسخ، در فایل OpenAPI است.

درخواست	کار	دسترسی لازم
`GET /api/v1/me`	شناسایی کلید و فضای کاری	`—`
`GET /api/v1/usage`	مصرف فضا، پهنای باند و بازدید	`analytics:read`
`GET /api/v1/videos`	فهرست ویدئوهای فضای کاری	`videos:read`
`GET /api/v1/videos/{id}`	دریافت جزئیات یک ویدئو	`videos:read`
`PATCH /api/v1/videos/{id}`	ویرایش اطلاعات یا سطح دسترسی ویدئو	`videos:write`
`DELETE /api/v1/videos/{id}`	حذف ویدئو	`videos:write`
`GET /api/v1/videos/{id}/playback`	اطلاعات پخش ویدئو	`videos:read`
`PUT /api/v1/videos/{id}/collections`	تعیین مجموعه‌های یک ویدئو	`collections:write`
`GET /api/v1/videos/{id}/subtitles`	فهرست زیرنویس‌های ویدئو	`videos:read`
`POST /api/v1/videos/{id}/subtitles`	افزودن زیرنویس	`subtitles:write`
`PATCH /api/v1/videos/{id}/subtitles/{subtitleId}`	ویرایش زیرنویس	`subtitles:write`
`DELETE /api/v1/videos/{id}/subtitles/{subtitleId}`	حذف زیرنویس	`subtitles:write`
`GET /api/v1/videos/{id}/thumbnails`	فهرست تصاویر شاخص	`videos:read`
`POST /api/v1/videos/{id}/thumbnails`	انتخاب تصویر شاخص	`videos:write`
`POST /api/v1/uploads`	شروع بارگذاری و دریافت نشانی آپلود	`uploads:write`
`POST /api/v1/uploads/{id}/complete`	پایان بارگذاری و ارسال به صف پردازش	`uploads:write`
`GET /api/v1/collections`	فهرست مجموعه‌ها	`collections:read`
`POST /api/v1/collections`	ساخت مجموعه	`collections:write`
`GET /api/v1/collections/{id}`	دریافت جزئیات مجموعه	`collections:read`
`PATCH /api/v1/collections/{id}`	ویرایش مجموعه	`collections:write`
`DELETE /api/v1/collections/{id}`	حذف مجموعه	`collections:write`
`POST /api/v1/collections/{id}/videos`	افزودن ویدئو به مجموعه	`collections:write`
`DELETE /api/v1/collections/{id}/videos`	حذف ویدئو از مجموعه	`collections:write`
`PUT /api/v1/collections/{id}/order`	تغییر ترتیب ویدئوهای مجموعه	`collections:write`
`GET /api/v1/analytics/videos/{id}`	آمار تماشای یک ویدئو	`analytics:read`
`GET /api/v1/analytics/workspace`	آمار تماشای کل فضای کاری	`analytics:read`

خطاها

یک پوشش برای همهٔ پاسخ‌ها

پاسخ موفق همیشه ok: true دارد و پاسخ ناموفق ok: false به‌همراه یک کد ماشین‌خوان. روی code شرط بگذارید، نه روی متن پیام.

{
  "ok": false,
  "error": {
    "code": "quota_exceeded",
    "message": "The workspace has no storage left on its current plan.",
    "messageFa": "...",
    "docs": "https://ttve.ir/developers#errors"
  }
}

code	HTTP	یعنی چه
`unauthenticated`	`401`	برای ادامه وارد حساب شوید.
`forbidden`	`403`	این درخواست مجاز نیست.
`validation`	`400`	اطلاعات واردشده معتبر نیست.
`not_found`	`404`	مورد پیدا نشد.
`conflict`	`409`	این تغییر با وضعیت فعلی سازگار نیست.
`not_ready`	`409`	تا آماده شدن ویدئو امکان انتشار وجود ندارد.
`too_large`	`413`	حجم فایل بیشتر از حد مجاز است.
`quota_exceeded`	`413`	فضای ذخیره‌سازی این فضای کاری کافی نیست.
`internal`	`500`	مشکلی پیش آمد. دوباره تلاش کنید.

محدودیت درخواست روی هر کلید و در بازهٔ یک‌دقیقه‌ای اعمال می‌شود. هر پاسخ سه هدر X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset دارد؛ پاسخ ۴۲۹ هدر Retry-After هم می‌دهد.

برای عامل‌های هوش مصنوعی

TTVE را مستقیم به ابزار هوش مصنوعی‌تان وصل کنید

سرور MCP TTVE با همان کلید API کار می‌کند. ابزارهایی که نمایش داده می‌شوند دقیقاً همان‌هایی هستند که دسترسی کلید اجازه می‌دهد.

نشانی سرور MCP

https://ttve.ir/api/mcp

Authorization: Bearer ttve_live_...

انتقال Streamable HTTP. نسخه‌های پشتیبانی‌شدهٔ پروتکل: 2026-07-28، 2025-11-25، 2025-06-18، 2025-03-26.

فایل‌های ماشین‌خوان

/llms.txt — فهرست کوتاه و لینک‌محور
/llms-full.txt — کل این مستندات در یک فایل متنی
/api/v1/openapi.json — مشخصات OpenAPI 3.1

ابزارهای در دسترس

get_workspace_info
شناسایی کلید و فضای کاری
get_workspace_usage
مصرف فضا، پهنای باند و بازدید
list_videos
فهرست ویدئوهای فضای کاری
get_video
دریافت جزئیات یک ویدئو
update_video
ویرایش اطلاعات یا سطح دسترسی ویدئو
delete_video
حذف ویدئو
get_playback_info
اطلاعات پخش ویدئو
create_upload
شروع بارگذاری و دریافت نشانی آپلود
complete_upload
پایان بارگذاری و ارسال به صف پردازش
list_collections
فهرست مجموعه‌ها
create_collection
ساخت مجموعه
get_collection
دریافت جزئیات مجموعه
add_video_to_collection
افزودن ویدئو به مجموعه
get_video_analytics
آمار تماشای یک ویدئو
get_workspace_analytics
آمار تماشای کل فضای کاری

بارگذاری از راه MCP فایل را جابه‌جا نمی‌کند: ابزار create_upload فقط نشانی می‌دهد و فرستادن بایت‌ها همچنان با یک درخواست HTTP انجام می‌شود.

کلیدتان را بسازید و شروع کنید

ثبت‌نام رایگان است. یک کلید بسازید، اولین ویدئو را از کد خودتان بارگذاری کنید و چند دقیقه بعد لینک پخش بگیرید.

شروع رایگان