Chuyển đến nội dung chính
XPNCORE

Tài liệu

Tạo video bằng API

Tạo video từ mô tả hoặc từ ảnh qua POST /v1/videos, theo dõi trạng thái và tải file về.

Điều hướng tài liệu

Duyệt hướng dẫn API và các mục trong trang này.

Video được tạo trong nền: gửi yêu cầu, hỏi trạng thái cho tới khi xong, rồi tải file. API giữ dạng Videos API của OpenAI và thêm tỉ lệ khung, độ phân giải, khung hình đầu/cuối.

Điểm cần nhớ

  • Lấy model video từ GET /v1/models: model có videos.generations trong endpoints.
  • POST /v1/videos trả ngay id; trạng thái đi từ queued → in_progress → completed hoặc failed.
  • Tải file bằng GET /v1/videos/{id}/content; video được giữ tới expires_at.
  • Giá = giá gốc × hệ số độ dài × hệ số độ phân giải; tiền chỉ bị trừ khi video đã lưu xong.
  • Video lỗi, bị hủy hoặc quá giờ không bị tính phí.

Cách hoạt động#

Tạo video mất thời gian, nên API chạy theo kiểu tác vụ nền, giống Videos API của OpenAI:

  1. Tạo: POST /v1/videos trả ngay một object video ở trạng thái queued, kèm id.
  2. Theo dõi: gọi GET /v1/videos/{id} mỗi 10–15 giây. status chuyển sang in_progress, rồi completed hoặc failed.
  3. Tải về: khi completed, tải file bằng GET /v1/videos/{id}/content.

Một video thường xong trong 1–3 phút. Quá thời gian cho phép (hiện là 20 phút) mà chưa xong thì tác vụ dừng với lỗi VIDEO_TIMEOUT và bạn không mất tiền.

Tạo video đầu tiên#

Đoạn code dưới đây làm đủ ba bước: tạo một video 8 giây 16:9 ở 720p, chờ xong rồi lưu thành boat.mp4. Lấy VIDEO_MODEL_ID từ GET /v1/models: model video có videos.generations trong endpoints.

POST /v1/videos → GET /v1/videos/{id} → GET /v1/videos/{id}/content
# 1. Create the video
VIDEO_ID=$(curl -s https://api.xpncore.com/v1/videos \
  -H "Authorization: Bearer $XPNCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "VIDEO_MODEL_ID",
    "prompt": "A paper boat drifting down a rainy neon street, slow dolly shot",
    "seconds": "8",
    "size": "1280x720"
  }' | jq -r '.id')

# 2. Check every 10 seconds until it is completed or failed
while true; do
  STATUS=$(curl -s https://api.xpncore.com/v1/videos/$VIDEO_ID \
    -H "Authorization: Bearer $XPNCORE_API_KEY" | jq -r '.status')
  echo "$STATUS"
  case "$STATUS" in completed|failed) break ;; esac
  sleep 10
done

# 3. Download the file
curl -L https://api.xpncore.com/v1/videos/$VIDEO_ID/content \
  -H "Authorization: Bearer $XPNCORE_API_KEY" \
  -o boat.mp4
200 OK · POST /v1/videos
{
  "id": "4c102af4-5d04-444c-846e-05f1eefccf7b",
  "object": "video",
  "model": "VIDEO_MODEL_ID",
  "status": "queued",
  "progress": 0,
  "created_at": 1759550400,
  "completed_at": null,
  "expires_at": null,
  "seconds": "8",
  "size": "1280x720",
  "prompt": "A paper boat drifting down a rainy neon street, slow dolly shot",
  "remixed_from_video_id": null,
  "error": null
}

Tham số khi tạo video#

Gửi JSON, hoặc multipart/form-data khi có file ảnh. Body tối đa 48 MB. Các trường mà model không hỗ trợ sẽ bị từ chối với lỗi 422 VIDEO_OPTION_UNSUPPORTED, kèm lời giải thích.

modelstringBắt buộc

ID model video lấy từ GET /v1/models.

promptstringBắt buộc

Mô tả video, tối đa 4.000 ký tự: chủ thể, hành động, bối cảnh, chuyển động máy quay, âm thanh.

secondsstring | integerKhông bắt buộc

Độ dài video, ví dụ "4", "6", "8". Có thể gửi duration thay cho trường này. Mặc định theo model (thường là 8).

sizestringKhông bắt buộc

WIDTHxHEIGHT, ví dụ 1280x720 (16:9, 720p) hoặc 720x1280 (9:16, 720p). Có thể gửi aspect_ratio và resolution thay cho trường này.

aspect_ratiostringKhông bắt buộc

Tỉ lệ khung, ví dụ 16:9 hoặc 9:16.

resolutionstringKhông bắt buộc

Độ phân giải, ví dụ 720p, 1080p, 4k. Độ phân giải cao thường chỉ có ở độ dài 8 giây.

input_referencefile | stringKhông bắt buộc

Ảnh làm khung hình đầu tiên (xem phần Tạo video từ ảnh). Cũng nhận tên first_frame hoặc image.

last_framefile | stringKhông bắt buộc

Ảnh làm khung hình cuối; cần đi kèm khung hình đầu.

reference_imagesarrayKhông bắt buộc

Tối đa 3 ảnh tham chiếu cho nhân vật hoặc phong cách. Không dùng chung với khung đầu/cuối, và thường chỉ ở độ dài 8 giây.

negative_promptstringKhông bắt buộc

Những gì không muốn xuất hiện, tối đa 1.000 ký tự, nếu model hỗ trợ.

seedintegerKhông bắt buộc

Số từ 0 đến 4294967295 để kết quả lặp lại được hơn, nếu model hỗ trợ.

Tỉ lệ khung, độ dài và độ phân giải#

size được đổi thành tỉ lệ khung và độ phân giải: cạnh ngắn hơn là độ phân giải.

  • 1280x720 → 16:9, 720p · 720x1280 → 9:16, 720p
  • 1920x1080 → 16:9, 1080p · 1080x1920 → 9:16, 1080p
  • 3840x2160 → 16:9, 4k

Mỗi model có bộ lựa chọn riêng. Phổ biến nhất: tỉ lệ 16:9 và 9:16; độ dài 4, 6 hoặc 8 giây; 720p ở mọi độ dài, còn 1080p và 4k chỉ ở 8 giây. Không gửi trường nào thì model dùng mặc định của nó (thường là 16:9, 8 giây, 720p). Hầu hết model tạo video kèm âm thanh.

Tạo video từ ảnh#

Gửi ảnh trong input_reference để video bắt đầu từ đúng khung hình đó. Ảnh có thể là:

  • một file trong multipart (như code mẫu),
  • một data URL data:image/png;base64,... hoặc chuỗi base64 trong body JSON,
  • một link https:// công khai (tải trong tối đa 20 giây).

Ảnh phải là PNG, JPEG hoặc WebP, tối đa 10 MB. Nên dùng ảnh cùng tỉ lệ khung với video. Thêm last_frame để chọn luôn khung hình kết thúc.

POST /v1/videos · multipart/form-data
curl https://api.xpncore.com/v1/videos \
  -H "Authorization: Bearer $XPNCORE_API_KEY" \
  -F model=VIDEO_MODEL_ID \
  -F prompt="The boat slowly sails away as the rain stops" \
  -F seconds=8 \
  -F size=1280x720 \
  -F [email protected]

Theo dõi trạng thái#

Object video giữ nguyên dạng của OpenAI Videos API:

  • queued: đang chờ tới lượt.
  • in_progress: đang tạo; progress cho biết phần trăm (0–100).
  • completed: xong; tải file được tới thời điểm expires_at.
  • failed: không tạo được; error.code và error.message cho biết lý do. Video lỗi không bị tính phí.

Thời gian là Unix giây. Hãy hỏi trạng thái mỗi 10–15 giây; hỏi dày hơn không làm video xong nhanh hơn.

200 OK · GET /v1/videos/{id}
{
  "id": "4c102af4-5d04-444c-846e-05f1eefccf7b",
  "object": "video",
  "model": "VIDEO_MODEL_ID",
  "status": "completed",
  "progress": 100,
  "created_at": 1759550400,
  "completed_at": 1759550492,
  "expires_at": 1760155292,
  "seconds": "8",
  "size": "1280x720",
  "prompt": "A paper boat drifting down a rainy neon street, slow dolly shot",
  "remixed_from_video_id": null,
  "error": null
}

Tải video về#

GET /v1/videos/{id}/content trả về chính file video (thường là video/mp4) và hỗ trợ header Range, nên có thể phát hoặc tải tiếp từ giữa chừng.

  • Video được giữ tới expires_at (hiện là 7 ngày sau khi xong), rồi tự xóa. Hãy tải về và tự lưu nếu cần dùng lâu.
  • Chưa xong: lỗi 404 VIDEO_NOT_READY. Đã xóa hoặc hết hạn: lỗi 404 VIDEO_GONE.
  • Video tạo bằng API và trong Chat AI › Tạo video dùng chung một kho lưu trữ cho mỗi tài khoản (hiện là 2 GB).

Liệt kê và xóa video#

  • GET /v1/videos liệt kê video mới nhất trước. Tham số: limit (1–100, mặc định 20), after (id cuối của trang trước), order (desc hoặc asc). Response có data, first_id, last_id và has_more.
  • DELETE /v1/videos/{id}: video còn queued thì bị hủy và hoàn tiền; video đã xong thì file bị xóa để giải phóng dung lượng. Video đang tạo không hủy được (lỗi 409 VIDEO_NOT_CANCELLABLE).
GET /v1/videos · DELETE /v1/videos/{id}
# The 20 newest videos
curl "https://api.xpncore.com/v1/videos?limit=20" \
  -H "Authorization: Bearer $XPNCORE_API_KEY"

# The next page: the videos after the last id of this one
curl "https://api.xpncore.com/v1/videos?limit=20&after=LAST_ID" \
  -H "Authorization: Bearer $XPNCORE_API_KEY"

# Delete a video (a queued one is cancelled and refunded)
curl -X DELETE https://api.xpncore.com/v1/videos/$VIDEO_ID \
  -H "Authorization: Bearer $XPNCORE_API_KEY"

Giá và cách tính tiền#

Giá tính theo từng video: giá gốc × hệ số độ dài × hệ số độ phân giải. Ví dụ, video 4 giây rẻ hơn 8 giây, còn 1080p và 4k đắt hơn 720p.

  1. Khi tạo, số tiền của video được tạm giữ trong ví.
  2. Chỉ khi file đã lưu xong mới trừ tiền, và không bao giờ vượt số đã giữ.
  3. Video lỗi, bị hủy hoặc quá giờ thì nhả toàn bộ số tiền đã giữ.

Giá gốc của từng model có ở trang Model & giá; giá chính xác cho từng lựa chọn hiện ngay trong Chat AI › Tạo video trước khi bạn tạo.

Lỗi thường gặp#

Lỗi khi tạo video (request bị từ chối ngay, không giữ tiền):

  • 402 INSUFFICIENT_FUNDS: số dư ví không đủ cho giá video.
  • 409 VIDEO_TOO_MANY_ACTIVE: đã đủ số video được tạo cùng lúc (hiện là 3); chờ một video xong rồi thử lại.
  • 409 VIDEO_STORAGE_FULL: kho video đã đầy; xóa bớt video cũ.
  • 422 VIDEO_OPTION_UNSUPPORTED: model không có tỉ lệ, độ dài, độ phân giải hoặc kiểu ảnh đầu vào đó.
  • 400 CONTENT_POLICY_BLOCKED: prompt vi phạm chính sách nội dung.
  • 503 MODEL_PRICING_UNAVAILABLE: model chưa có giá, tạm thời chưa dùng được.

Lỗi trong error.code của video failed (không bị tính phí):

  • VIDEO_CONTENT_BLOCKED: bộ lọc an toàn từ chối nội dung; hãy viết lại prompt hoặc đổi ảnh.
  • VIDEO_TIMEOUT: quá thời gian cho phép mà chưa xong.
  • VIDEO_UPSTREAM_FAILED, VIDEO_NO_CAPACITY: model đang quá tải hoặc gián đoạn; thử lại sau ít phút.
  • VIDEO_DOWNLOAD_FAILED, VIDEO_TOO_LARGE, VIDEO_NOT_VIDEO: file kết quả không lấy về được hoặc không hợp lệ.
  • VIDEO_CANCELLED: bạn đã hủy video.

Endpoint tương thích#

Ngoài /v1/videos, gateway còn nhận POST /v1/video/generations và GET /v1/video/generations/{id} cho các công cụ quen dạng này. Hai endpoint dùng cùng tham số, nhưng object trả về có object: "video.generation" và trạng thái queued, processing, succeeded, failed. Khi xong, video_url trỏ tới /v1/videos/{id}/content (cần khóa API).

Muốn thử nhanh không cần code, hoặc nối dài một video đã tạo, hãy dùng Chat AI › Tạo video trong bảng điều khiển.

Mở trình hướng dẫn thiết lậpPlayground