Video Generation API

Tạo video từ text, ảnh, hoặc kéo dài video có sẵn — hỗ trợ Google Veo, OpenAI Sora 2, ByteDance Seedance và Kuaishou Kling.

Không cần viết code: có thể tạo video ngay trong AI Studio trên Dashboard. Video hướng dẫn:

2:18

Endpoint

Tạo video

POST https://platform.beeknoee.com/v1/video/generations

Kiểm tra trạng thái

GET https://platform.beeknoee.com/v1/video/generations/:id

Lấy hàng loạt video đã tạo (list)

GET https://platform.beeknoee.com/v1/video/generations?limit=20&offset=0

Trả về danh sách video bạn đã tạo, mới nhất trước. Query params: limit (mặc định 20, tối đa 100) · offset (phân trang).

{
  "jobs": [
    {
      "job_id": "abc-123",
      "status": "COMPLETED",
      "model": "veo-3.1-fast-generate-preview",
      "prompt": "a golden retriever running...",
      "resolution": "720p",
      "duration": "4",
      "aspect_ratio": "16:9",
      "cost_vnd": 12000,
      "video_url": "/v1/video/generations/abc-123/download",
      "created_at": "2026-07-08T10:00:00.000Z"
    }
  ],
  "total": 8,
  "limit": 20,
  "offset": 0
}

💡 Duyệt danh sách (lặp offset) rồi tải từng video_url là bạn get được hàng loạt video đã tạo.

Download video

GET https://platform.beeknoee.com/v1/video/generations/:id/download

⏳ Thời gian lưu video & Thư viện

• Video được lưu 1 ngày (24 giờ) kể từ lúc tạo, sau đó tự động xóa (video nặng hơn ảnh nhiều) — hãy tải về trong ngày.
• Xem lại video đã tạo (còn hạn) trên dashboard tại Playground - Media → Thư viện: có preview, thông số, thời gian còn lại và nút tải. Video/ảnh hết hạn tự ẩn.
• Sau 24 giờ, video không tải được nữa — cần tạo lại.

Request — Tạo Video

Headers

Body Parameters

💡 Passthrough Pattern: Chỉ gửi params bạn cần — params không gửi sẽ dùng default của Google. Không cần gửi tất cả fields.

5 Dạng Input

1. Text-to-Video (mặc định)

Chỉ cần prompt — AI tạo video hoàn toàn từ mô tả text.

{
  "model": "veo-3.1-fast-generate-preview",
  "prompt": "A cinematic 4K shot of a golden retriever running through sunflower field at sunset",
  "duration": "8",
  "aspect_ratio": "16:9"
}

2. Image-to-Video

Gửi kèm image (base64) — ảnh sẽ thành frame đầu tiên của video.

{
  "prompt": "The flowers in the image slowly bloom and sway in the wind",
  "image": "iVBORw0KGgo... (base64 PNG/JPG)"
}

3. Dual Frame Control

Gửi image + last_frame — kiểm soát cả frame đầu và frame cuối của video.

{
  "prompt": "Smooth transition from day to night in a city scene",
  "image": "base64_frame_đầu...",
  "last_frame": "base64_frame_cuối..."
}

4. Reference Images (Style Transfer)

Gửi reference_images (tối đa 3 ảnh) — video sẽ theo phong cách của ảnh tham chiếu.

{
  "prompt": "A girl walking through a garden with butterflies",
  "reference_images": [
    "base64_ảnh_style_1...",
    "base64_ảnh_style_2..."
  ]
}

5. Video Extension

Gửi video (URI) — kéo dài video có sẵn thêm thời lượng.

{
  "prompt": "Continue the scene smoothly with same camera angle",
  "video": "https://generativelanguage.googleapis.com/v1beta/files/abc123"
}

⚠️ Lưu ý Video Extension: Google không hỗ trợ upload video dạng base64. Field video phải là URI theo chuẩn Google (từ video đã generate trước hoặc GCS URI). Video trên Google chỉ giữ 2 ngày.

Models khả dụng

Google Veo

ℹ️ Veo 3 và Veo 2 (veo-3.0-*, veo-2.0-*) đã ngừng phục vụ — gọi vào sẽ báo model không tồn tại. Dùng Veo 3.1 thay thế.

OpenAI Sora

ByteDance Seedance

ℹ️ Các biến thể seedance-2-omni-* và seedance-2-remix-* không còn phục vụ — dùng seedance-2-fast / seedance-2-pro.

Kuaishou Kling

💡 Khác biệt chính: Veo hỗ trợ 5 dạng input (text, image, dual frame, reference images, video extension). Sora chỉ hỗ trợ text-to-video và image-to-video, nhưng video dài hơn (max 20s). Seedance hỗ trợ text-to-video, image-to-video (ref images), và video extension. Kling nhận text-to-video và image-to-video qua URL ảnh public.

💡 Giá và giới hạn thay đổi theo nhà cung cấp — số chính xác luôn xem tại trang Image & Video Models trên Dashboard.

Cách tính phí: giá × thời lượng (giây). VD: Veo 3.1 Fast 8 giây = $0.15 × 8 = $1.20.

🆕 Nhóm model video mới

Wan 3.0 / Wan 3.0 Prime / HappyHorse 1.1 (Alibaba), FLUX.3 Video, Seedance 2.0 Mini / 2.5, Veo 3.1 Lite, HeyGen Video, Kling Video O1, MiniMax H3 / H3 Max, Runway Gen-4.5, Grok Imagine Video 1.5 / 1.5 Lite — gọi cùng endpoint POST /v1/video/generations, Model ID dạng hãng/model (vd alibaba/wan-3.0, runway/gen-4.5):

Nhóm này không nhận negative_prompt, reference_images, video (báo lỗi 400, không trừ tiền).

Xem năng lực + giá: GET /models/video → trường media_pricing (caps.durations, caps.resolutions, caps.frameImages…; prices: USD/giây theo độ phân giải|tiếng|t2v-hoặc-i2v).

Cách tính phí: giá/giây × số giây (+ phí ảnh khung ở vài model, mức tối thiểu/lượt ở vài model). Video hỏng / bị chặn nội dung ⇒ không trừ tiền.

Response

Khi submit — nhận Job ID

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "estimated_time_seconds": 120
}

Khi poll status — đang xử lý

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PROCESSING",
  "model": "veo-3.1-fast-generate-preview",
  "prompt": "A cinematic shot...",
  "poll_count": 5,
  "elapsed_seconds": 50,
  "created_at": "2026-03-19T12:00:00Z"
}

Khi hoàn thành

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "model": "veo-3.1-fast-generate-preview",
  "prompt": "A cinematic shot...",
  "cost_vnd": 33000,
  "video_url": "/v1/video/generations/a1b2c3d4.../download",
  "source_url": "https://.../video.mp4",
  "elapsed_seconds": 120,
  "completed_at": "2026-03-19T12:02:30Z"
}

Response Fields

source_url theo Provider:

💡 Khuyến nghị: Luôn dùng video_url (proxy) để download. Dùng source_url khi muốn stream/xem trực tiếp mà không tải về (chỉ hoạt động với một số provider).

Trạng thái Video Job

Ví dụ

1. Text-to-Video

# Bước 1: Submit request
curl -X POST https://platform.beeknoee.com/v1/video/generations \
  -H "Authorization: Bearer sk-bee-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "A cat sitting on a windowsill watching rain fall outside",
    "duration": "8",
    "aspect_ratio": "16:9"
  }'

# Response: {"job_id": "abc-123", "status": "PENDING", ...}

# Bước 2: Poll status (lặp lại mỗi 5-10 giây)
curl https://platform.beeknoee.com/v1/video/generations/abc-123 \
  -H "Authorization: Bearer sk-bee-your-key"

# Khi status = "COMPLETED":

# Bước 3: Download video
curl -o output.mp4 \
  https://platform.beeknoee.com/v1/video/generations/abc-123/download \
  -H "Authorization: Bearer sk-bee-your-key"

import requests
import time

BASE_URL = "https://platform.beeknoee.com/v1"
API_KEY = "sk-bee-your-key"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Bước 1: Submit video request
response = requests.post(f"{BASE_URL}/video/generations", headers=headers, json={
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "A drone shot flying over rice fields in Vietnam at golden hour",
    "duration": "8",
    "aspect_ratio": "16:9",
    "person_generation": "allow_adult"
})

job = response.json()
job_id = job["job_id"]
print(f"✅ Job created: {job_id}")

# Bước 2: Poll cho đến khi hoàn thành
while True:
    status_res = requests.get(f"{BASE_URL}/video/generations/{job_id}", headers=headers)
    data = status_res.json()
    print(f"⏳ Status: {data['status']} (poll #{data.get('poll_count', '?')})")

    if data["status"] == "COMPLETED":
        print(f"🎉 Video hoàn thành! Cost: {data['cost_vnd']} VND")
        break
    elif data["status"] in ("FAILED", "TIMEOUT"):
        print(f"❌ Lỗi: {data.get('errorMessage', 'Unknown')}")
        break

    time.sleep(5)  # Poll mỗi 5 giây

# Bước 3: Download video
video_res = requests.get(f"{BASE_URL}/video/generations/{job_id}/download", headers=headers)
with open("output.mp4", "wb") as f:
    f.write(video_res.content)
print("📥 Đã lưu output.mp4")

const BASE_URL = 'https://platform.beeknoee.com/v1';
const API_KEY = 'sk-bee-your-key';

async function generateVideo() {
  // Bước 1: Submit request
  const res = await fetch(`${BASE_URL}/video/generations`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'veo-3.1-fast-generate-preview',
      prompt: 'A timelapse of clouds moving over mountains at sunrise',
      duration: '8',
      aspect_ratio: '16:9',
    }),
  });

  const { job_id } = await res.json();
  console.log(`✅ Job: ${job_id}`);

  // Bước 2: Poll status
  while (true) {
    const status = await fetch(`${BASE_URL}/video/generations/${job_id}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
    }).then(r => r.json());

    console.log(`⏳ ${status.status}`);

    if (status.status === 'COMPLETED') {
      console.log(`🎉 Done! Cost: ${status.cost_vnd} VND`);
      // Download: GET /video/generations/${job_id}/download
      break;
    }
    if (['FAILED', 'TIMEOUT'].includes(status.status)) {
      console.error(`❌ ${status.errorMessage}`);
      break;
    }

    await new Promise(r => setTimeout(r, 5000));
  }
}

generateVideo();

2. Image-to-Video — Python

import requests
import base64

BASE_URL = "https://platform.beeknoee.com/v1"
headers = {
    "Authorization": "Bearer sk-bee-your-key",
    "Content-Type": "application/json"
}

# Đọc ảnh và encode base64
with open("my_image.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

# Submit image-to-video request
response = requests.post(f"{BASE_URL}/video/generations", headers=headers, json={
    "prompt": "The scene in the image comes alive with gentle wind and falling leaves",
    "image": image_base64,
    "duration": "8"
})

job_id = response.json()["job_id"]
print(f"✅ Job: {job_id} — poll status tại GET /video/generations/{job_id}")

WebSocket — Realtime Updates (Tùy chọn)

Thay vì poll liên tục, bạn có thể kết nối WebSocket để nhận update realtime:

import { io } from 'socket.io-client';

const socket = io('https://platform.beeknoee.com', {
  auth: { token: 'sk-bee-your-key' }
});

socket.on('video:status', (data) => {
  console.log(`📡 Job ${data.jobId}: ${data.status}`);
  if (data.status === 'COMPLETED') {
    console.log(`🎉 Video ready! Cost: ${data.costVND} VND`);
  }
});

Billing

• Tính phí theo giây: giá_model × thời_lượng_video
• Giảm giá theo plan: BASIC (-5%), ADVANCED+ (-10%)
• Trừ tiền khi hoàn thành: Chỉ trừ ví VNĐ khi video COMPLETED
• Không charge lỗi: Video FAILED hoặc bị safety block → không tính phí
• Kiểm tra số dư trước: Nếu ví không đủ → reject ngay (400)

Ví dụ tính phí:

• Veo 3.1 Fast, 8 giây: $0.15 × 8 = $1.20
• Sora 2, 10 giây: $0.10 × 10 = $1.00
• Sora 2 Pro, 10 giây: $0.30 × 10 = $3.00
• Veo 2, 5 giây: $0.10 × 5 = $0.50
• Veo 3 Fast: Miễn phí
• Seedance 2 Omni Fast, 8 giây: $0.08 × 8 = $0.64
• Seedance 2 Omni Pro, 10 giây: $0.14 × 10 = $1.40
• Seedance 2 Remix Fast, 12 giây: $0.08 × 12 = $0.96

Error Handling

Giới hạn & Lưu ý

Best Practices

1. Prompt chi tiết — Mô tả rõ: góc camera, ánh sáng, chuyển động, phong cách (cinematic, anime, realistic...)
2. Negative prompt — Thêm blurry, low quality, watermark, distortion để tăng chất lượng
3. Download ngay — Video URL hết hạn sau 2 ngày, lưu về server/storage của bạn
4. Poll hợp lý — Mỗi 5-10 giây, tối đa 120 lần (10 phút)
5. Xử lý FAILED — Luôn handle case video bị block bởi safety filter
6. Bắt đầu với Fast — Dùng veo-3.1-fast-generate-preview để test prompt trước, chuyển sang veo-3.1-generate-preview khi cần chất lượng cao

Tiếp theo

• Chat Completions — Kết hợp AI text với video workflow
• Text Models — Xem danh sách models text
• API Usage — Theo dõi chi phí video generation
• Error Handling — Xử lý lỗi chi tiết