🎬
VN91PROJECT WORKSPACE

Tài Liệu Kỹ Thuật & Tích Hợp API (API Reference)

Base URL: https://api.vn91.netXác thực HTTP Header: Authorization: Bearer <API_KEY>Lấy API Key
POST

1. Khởi Tạo Tác Vụ Sinh Video

/v1/videos/generations

Khởi tạo job render video không đồng bộ (Async Task). API nhận request và trả về mã id lập tức. Hỗ trợ đầy đủ tham số ảnh tham chiếu, clone giọng và keyframe.

Tham Số (Field)KiểuMặc ĐịnhMô Tả & Quy Cách Hợp Lệ
promptstringBắt buộcMô tả cảnh quay video. Sử dụng <IMAGE_0>, <IMAGE_1> để tham chiếu ảnh và <AUDIO_0> để gán giọng đọc.
modelstringgrok-imagine-video-1.5grok-imagine-video-1.5 (HQ cao cấp), grok-imagine-video-1.5-lite (tốc độ), grok-imagine-video (v1.0).
durationint5Thời lượng video tính bằng giây: 5, 10, 15 giây.
aspect_ratiostring16:9Tỉ lệ khung hình: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2.
resolutionstring720pĐộ phân giải: 480p, 720p, 1080p. (Lưu ý: Nếu có ảnh hoặc giọng tham chiếu thì tối đa 720p).
reference_imagesstring[]nullDanh sách URL hoặc base64 ảnh tham chiếu nhân vật/bối cảnh (tối đa 14 ảnh).
reference_audiosstring[]nullDanh sách Voice ID (tối đa 3 giọng, xem tab Danh Mục Giọng Đọc). Gọi <AUDIO_0> trong prompt.
keyframesobject[]nullGhim frame giữa video: [{"image_url": "...", "timestamp_s": 2}] (tối đa 4 mốc, chỉ hỗ trợ trên video-1.5).
curl -X POST https://api.vn91.net/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The warrior from <IMAGE_0> walks toward camera, speaking with voice from <AUDIO_0>, cinematic 4k",
    "model": "grok-imagine-video-1.5",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "reference_images": ["https://cdn.example.com/character.jpg"],
    "reference_audios": ["eve"],
    "keyframes": [{"image_url": "https://cdn.example.com/mid.jpg", "timestamp_s": 2}]
  }'
GET

2. Tra Cứu Trạng Thái & Nhận URL Video MP4

/v1/videos/generations/{task_id}

Thực hiện polling định kỳ mỗi 3 - 5 giây. Khi status chuyển thành completed, URL video MP4 sẽ nằm trong mảng data[0].url.

curl -X GET https://api.vn91.net/v1/videos/generations/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response thành công (status = "completed"):

{
  "id": "310716a1-672e-9ae6-865f-3264efbd7015",
  "object": "video.generation",
  "created": 1792651344,
  "model": "grok-imagine-video-1.5",
  "status": "completed",
  "progress": 100,
  "data": [
    {
      "url": "https://vidgen.x.ai/xai-vidgen-bucket/xai-video-310716a1-672e-9ae6-865f-3264efbd7015.mp4"
    }
  ]
}
POST

3. Nối Dài Video Có Sẵn (Video Extension)

/v1/videos/extensions

Kéo dài video có sẵn (dài 2-15s) bằng cách sinh tiếp 2-10 giây cảnh quay mới liền mạch từ frame cuối cùng của video gốc. Tra cứu trạng thái qua cùng endpoint polling.

curl -X POST https://api.vn91.net/v1/videos/extensions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://vidgen.x.ai/xai-vidgen-bucket/sample.mp4",
    "prompt": "The warrior continues walking and enters a dark mystical cave",
    "duration": 6
  }'
POST

4. Chỉnh Sửa & Restyle Video Bằng Prompt

/v1/videos/edits

Biến đổi hoặc đổi phong cách video có sẵn (tối đa 8.7s) dựa trên prompt. Giữ nguyên chuyển động gốc nhưng thay đổi màu sắc, bối cảnh, ánh sáng hoặc nét vẽ.

curl -X POST https://api.vn91.net/v1/videos/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://vidgen.x.ai/xai-vidgen-bucket/sample.mp4",
    "prompt": "Restyle into anime Makoto Shinkai aesthetic with falling sakura petals"
  }'

Full Workflow Tích Hợp Bằng Python

import requests, time

API_KEY = "YOUR_API_KEY"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Create video generation task (Async)
res = requests.post(
    "https://api.vn91.net/v1/videos/generations",
    headers=headers,
    json={
        "prompt": "Cyberpunk street samurai fighting a robot, 4k ultra realistic",
        "model": "grok-imagine-video-1.5",
        "duration": 5,
        "aspect_ratio": "16:9"
    }
).json()

task_id = res["id"]
print(f"Task ID created: {task_id}")

# 2. Poll status until completed
while True:
    st = requests.get(f"https://api.vn91.net/v1/videos/generations/{task_id}", headers=headers).json()
    status = st.get("status")
    progress = st.get("progress", 0)
    print(f"Status: {status} ({progress}%)")

    if status == "completed":
        print(f"Video MP4 Ready: {st['data'][0]['url']}")
        break
    elif status == "failed":
        print(f"Generation failed: {st.get('error', {}).get('message')}")
        break
    time.sleep(3)