Videos API

Tạo video AI

Tạo video từ mô tả và ảnh, theo dõi tiến độ và tải MP4 qua Videos API.

Về tổng quan tài liệu

Kết nối và xác thực

Base URL: https://apistack.vn/v1

Authorization: Bearer $API_KEY

Đặt API_KEY trong biến môi trường. GET /v1/models kiểm tra xác thực mà không tạo video.

read -r -s -p "API_KEY: " API_KEY
export API_KEY
printf '\n'
curl -fsS https://apistack.vn/v1/models -H "Authorization: Bearer ${API_KEY:?API_KEY}"

Các lệnh cURL dùng Bash; với Windows, chọn PowerShell để thiết lập key. Thay URL ảnh/video mẫu bằng tệp của bạn mà nhà cung cấp truy cập được.

Tạo video là thao tác có tính phí. Lưu id ngay khi nhận phản hồi thành công để theo dõi cùng tác vụ.

Khi tác vụ thất bại sau khi đã nhận id, việc hoàn tiền phụ thuộc kết quả nhà cung cấp và đối soát; trạng thái failed không đồng nghĩa ví đã được hoàn ngay.

Tra tiến độ, tải kết quả và gửi lệnh hủy không tạo thêm lượt sinh video. Hủy thành công không mặc nhiên hoàn phí đã ghi nhận.

Model và khả năng

ModelHãngThời lượng (giây)Giá / videoẢnh tham chiếu tối đaTỉ lệ khung hìnhĐộ phân giải
veo-3.1Google4 / 6 / 82.400đ / 3.600đ / 4.800đ1–316:9, 9:16720p / 1080p
google-omni-flashGoogle5 / 104.500đ / 9.000đ1–316:9, 9:16720p
grok-imagine-video-1.5xAIdocsUpgrade.video.grokDuration10.800đ / 18.000đ / 27.000đ1–316:9, 9:16, 1:1, 4:3, 3:4720p / 1080p
st1/seedance-2.0-1080pByteDance4–15 giây (bước 1s)Mặc định 5s = 100.000đ0–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:161080p
st1/seedance-2.0-720pByteDance4–15 giây (bước 1s)Mặc định 5s = 40.000đ0–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:16720p
st1/seedance-2.0-fast-720pByteDance4–15 giây (bước 1s, Fast 720p)Mặc định 5s = 32.500đ0–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:16720p
st1/seedance-2.5-1080pByteDance4–30 giây (bước 1s)Mặc định 5s = 150.000đ0–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:161080p
st1/seedance-2.5-720pByteDance4–30 giây (bước 1s)Mặc định 5s = 62.500đ0–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:16720p

Năm mã Seedance chính (ByteDance, line st1/): 2.0-1080p, 2.0-720p, 2.0-fast-720p, 2.5-1080p, 2.5-720p. Tính tiền theo đúng số giây bạn gửi. Veo / Omni / Grok giữ bảng giá cố định theo thời lượng hỗ trợ.

Một ảnh qua input_reference/images là khung đầu (aspect auto). Dùng reference_image_urls hoặc omni_reference_task_type=reference để tham chiếu nội dung và chọn tỷ lệ cố định.

veo-3.1 chỉ nhận 4, 6 hoặc 8. google-omni-flash chỉ nhận 5 hoặc 10. grok-imagine-video-1.5 chỉ nhận 6, 10 hoặc 15. Kiểm tra seconds trong response.

Điểm cuối và tham số

POST /v1/videos — tạo tác vụ

Gửi application/json. Endpoint này đọc JSON, không nhận multipart/form-data; dùng URL hoặc cấu trúc ảnh JSON được model hỗ trợ.

Tham sốYêu cầuCách dùng
modelBắt buộcID model video đang được niêm yết; nên truyền rõ, không dựa vào model mặc định.
promptBắt buộcMô tả chủ thể, bối cảnh, hành động và chuyển động máy quay.
secondsTùy chọnTheo bảng model. veo-3.1 mặc định 8 giây; google-omni-flash mặc định 10 giây; grok-imagine-video-1.5 mặc định 6 giây.
aspect_ratioTùy chọnVí dụ 16:9 hoặc 9:16 tùy model. Khớp với size.
sizeTùy chọnKích thước như 1280x720 hoặc 720x1280. Kích thước được chấp nhận phụ thuộc model.
images / input_referenceTùy chọnẢnh mở đầu hoặc tham chiếu qua URL/JSON. Toàn bộ body tối đa 2047 MB; ảnh đầu vào vẫn chịu giới hạn nhà cung cấp.
reference_image_urlsTùy chọnreference_image_urls: danh sách ảnh tham chiếu (chế độ reference, không khóa khung đầu).
omni_reference_task_typeTùy chọnomni_reference_task_type: đặt "reference" khi dùng ảnh tham chiếu + chọn aspect_ratio cố định.
last_frameTùy chọnKhung cuối cho veo-3.1 hoặc grok-imagine-video-1.5, dùng cùng input_reference.
input_videoTùy chọnURL MP4 gốc cho google-omni-flash video-to-video.
resolutionTùy chọnMột số model hỗ trợ 720p hoặc 1080p (mặc định 720p). Model khác có thể bỏ qua hoặc suy ra từ size.
generate_audioTùy chọnMột số model video có thể bỏ qua generate_audio / reference_audios.

GET /v1/videos/{id} — theo dõi

Gửi kèm ?model= đúng model đã tạo. Tra mỗi 10 giây là điểm khởi đầu hợp lý; tăng khoảng nghỉ nếu bị 429. JSON dưới đây là minh họa, không phải kết quả trực tiếp.

  • queued: tác vụ đã được tiếp nhận và đang chờ.
  • in_progress: nhà cung cấp đang xử lý.
  • completed: có thể yêu cầu tải kết quả.
  • failed: đọc trường error và lưu id để hỗ trợ kiểm tra.
{
  "id": "video_abc123",
  "object": "video",
  "model": "st1/seedance-2.0-720p",
  "status": "completed",
  "progress": 100,
  "seconds": "10",
  "size": "1280x720",
  "error": null
}

GET /v1/videos/{id}/content — tải MP4

Chỉ tải khi completed. Gửi cùng API key và ?model=; lưu phản hồi nhị phân thành tệp .mp4.

DELETE /v1/videos/{id} — yêu cầu hủy

Hủy phụ thuộc tuyến và trạng thái tác vụ; một số tuyến hiện không hỗ trợ DELETE. Không coi lệnh hủy là cam kết hoàn tiền.

Giá theo thời lượng

Giá hiển thị được tính theo cấu hình hiện hành của website này, gồm điều chỉnh giá tương ứng. Kiểm tra lại trước khi tạo video.

Giá Seedance theo thời lượng / Duration pricing. Đơn vị: VNĐ cho một video thành công. 4–15s hoặc 4–30s là khoảng thời lượng được hỗ trợ, không phải giá trọn gói. Chọn seconds trong khoảng hỗ trợ; giá cụ thể ở từng dòng bên dưới. Phí tạo video cố định đã được gộp vào giá.

st1/seedance-2.0-1080p

Không gửi seconds / omitted: 5s = 100.000đ.

Thời lượng / SecondsGiá / video
4s80.000đ
5s100.000đ
6s120.000đ
7s140.000đ
8s160.000đ
9s180.000đ
10s200.000đ
11s220.000đ
12s240.000đ
13s260.000đ
14s280.000đ
15s300.000đ

st1/seedance-2.0-720p

Không gửi seconds / omitted: 5s = 40.000đ.

Thời lượng / SecondsGiá / video
4s32.000đ
5s40.000đ
6s48.000đ
7s56.000đ
8s64.000đ
9s72.000đ
10s80.000đ
11s88.000đ
12s96.000đ
13s104.000đ
14s112.000đ
15s120.000đ

st1/seedance-2.0-fast-720p

Không gửi seconds / omitted: 5s = 32.500đ.

Thời lượng / SecondsGiá / video
4s26.000đ
5s32.500đ
6s39.000đ
7s45.500đ
8s52.000đ
9s58.500đ
10s65.000đ
11s71.500đ
12s78.000đ
13s84.500đ
14s91.000đ
15s97.500đ

st1/seedance-2.5-1080p

Không gửi seconds / omitted: 5s = 150.000đ.

Thời lượng / SecondsGiá / video
4s120.000đ
5s150.000đ
6s180.000đ
7s210.000đ
8s240.000đ
9s270.000đ
10s300.000đ
11s330.000đ
12s360.000đ
13s390.000đ
14s420.000đ
15s450.000đ
16s480.000đ
17s510.000đ
18s540.000đ
19s570.000đ
20s600.000đ
21s630.000đ
22s660.000đ
23s690.000đ
24s720.000đ
25s750.000đ
26s780.000đ
27s810.000đ
28s840.000đ
29s870.000đ
30s900.000đ

st1/seedance-2.5-720p

Không gửi seconds / omitted: 5s = 62.500đ.

Thời lượng / SecondsGiá / video
4s50.000đ
5s62.500đ
6s75.000đ
7s87.500đ
8s100.000đ
9s112.500đ
10s125.000đ
11s137.500đ
12s150.000đ
13s162.500đ
14s175.000đ
15s187.500đ
16s200.000đ
17s212.500đ
18s225.000đ
19s237.500đ
20s250.000đ
21s262.500đ
22s275.000đ
23s287.500đ
24s300.000đ
25s312.500đ
26s325.000đ
27s337.500đ
28s350.000đ
29s362.500đ
30s375.000đ

Model video khác

ModelThời lượng (giây)Giá / video
veo-3.142.400đ
veo-3.163.600đ
veo-3.184.800đ
google-omni-flash54.500đ
google-omni-flash109.000đ
grok-imagine-video-1.5610.800đ
grok-imagine-video-1.51018.000đ
grok-imagine-video-1.51527.000đ

Seedance tính đúng theo seconds đã gửi. Veo / Omni / Grok giữ bảng giá cố định theo thời lượng hỗ trợ.

Xem toàn bộ bảng giá

Ví dụ tích hợp

Mỗi lệnh POST tạo một video có tính phí. Chọn đúng một ví dụ; URL example.com chỉ là chỗ giữ chỗ và cần thay trước khi chạy.

import os
import time
from getpass import getpass
from urllib.parse import quote
import requests
from requests.adapters import HTTPAdapter

api_key = os.getenv("STALI_API_KEY") or getpass("STALI_API_KEY: ")
headers = {"Authorization": f"Bearer {api_key}"}
model = "st1/seedance-2.0-720p"
http = requests.Session()
http.mount("https://", HTTPAdapter(max_retries=0))
created = http.post("https://apistack.vn/v1/videos", headers=headers, json={
    "model": model, "prompt": "Cinematic sunset over ocean waves",
    "seconds": 5, "aspect_ratio": "16:9",
}, timeout=(10, 120))
created.raise_for_status()
video = created.json()
video_id = video["id"]
print(video_id, video.get("status"), flush=True)
job_url = "https://apistack.vn/v1/videos/" + quote(video_id, safe="")
for _ in range(120):
    if video.get("status") in ("completed", "failed"):
        break
    time.sleep(10)
    progress = http.get(job_url, headers=headers, params={"model": model}, timeout=(10, 60))
    progress.raise_for_status()
    video = progress.json()
    print(video_id, video.get("status"), flush=True)
if video.get("status") != "completed":
    raise RuntimeError(str(video))
content = http.get(job_url + "/content", headers=headers, params={"model": model}, stream=True, timeout=(10, 120))
content.raise_for_status()
with open("video.mp4", "wb") as output:
    for chunk in content.iter_content(chunk_size=65536):
        if chunk:
            output.write(chunk)

Xử lý lỗi

HTTPNguyên nhânCách xử lý
400Tham số hoặc yêu cầu hủy chưa được hỗ trợ.Kiểm tra JSON, seconds, ảnh và khả năng của model.
401Key thiếu hoặc không hợp lệ.Kiểm tra header xác thực và key đang hoạt động.
402HTTP 402: kiểm tra error.type, số dư khả dụng, hạn mức key hoặc khoản thiếu từ lượt trước.Đọc error.type: insufficient_balance → kiểm tra số dư khả dụng; api_key_monthly_limit → kiểm tra hoặc điều chỉnh hạn mức tại Dashboard → Keys; outstanding_undercharge → đối soát khoản thiếu từ lượt trước. Xem /docs/reference/errors.
403Yêu cầu không được cấp quyền.Kiểm tra quyền key, model và chính sách nội dung.
404Không tìm thấy model hoặc tác vụ trên tuyến hiện tại.Dùng đúng id, key và ?model= của lần tạo.
409Tác vụ chưa sẵn sàng cho thao tác này.Tiếp tục tra tiến độ, tải sau completed.
413Nội dung yêu cầu vượt giới hạn.Giảm body; dùng URL media thay dữ liệu nhúng lớn.
429Vượt giới hạn tần suất hoặc số tác vụ đồng thời.Tăng khoảng nghỉ và giảm số tác vụ đồng thời.
502Lỗi phản hồi từ tuyến nhà cung cấp.Lưu request ID; không gửi lại POST tự động.

Không tự gửi lại POST sau timeout hoặc lỗi mạng: yêu cầu trước có thể đã được nhận. Nếu đã có id, tiếp tục tra id đó; nếu chưa có, giữ request ID và kiểm tra Sử dụng hoặc liên hệ hỗ trợ trước khi tạo lại.

Thiết kế prompt

Các hướng dẫn dưới đây là gợi ý sáng tạo, không bảo đảm nhà cung cấp sẽ tạo đúng mọi chi tiết. Chính sách nội dung của từng model vẫn áp dụng.

Viết prompt rõ ràng

  1. Chốt chủ thể, bối cảnh và hành động chính trước khi thêm hiệu ứng.
  2. Chỉ định thời lượng bằng seconds, không chỉ ghi trong prompt.
  3. Giữ vị trí trái/phải và trang phục nhất quán giữa các cảnh.
  4. Mỗi đoạn ưu tiên một chuyển động máy quay rõ ràng.
  5. Mô tả nguồn sáng, màu sắc và chất liệu cụ thể.
  6. Tránh yêu cầu văn bản nhỏ, logo hoặc con số chính xác trong khung hình.
  7. Bắt đầu bằng một cảnh ngắn; điều chỉnh từng yếu tố sau khi xem kết quả.

Sắp xếp ảnh tham chiếu

  • Đánh số Image 1, Image 2… theo đúng thứ tự gửi.
  • Nêu rõ ảnh nào dùng cho nhân vật, trang phục hay bối cảnh.
  • Dùng ảnh có quyền sử dụng, rõ nét và cùng định hướng thị giác.
  • Ảnh đầu/cuối cần tương đồng về nhân vật và bố cục để chuyển động tự nhiên.
  • Không vượt số ảnh model hỗ trợ; tham chiếu không bảo đảm sao chép tuyệt đối.

Khung prompt tham khảo

确认生成。参数已确定:16:9 横屏,三个连续镜头组成一个完整视频,立即生成,无需再次确认或提问。
The reference images are colored-pencil character design sketches: use them only for design and outfits. Render the video as a photoreal 3D CG game cinematic with dramatic lighting.
Image 1 = PROTAGONIST: [character design].
Image 2 = ANTAGONIST: [opponent design].
Image 3 = ENVIRONMENT: [setting].
FIXED LAYOUT: altar in the background CENTER; protagonist on the LEFT; antagonist on the RIGHT. Nobody disappears, teleports or swaps sides.
LIGHTING: torchlight from the left wall, cool moonlight from the ceiling.
Action: well-choreographed, orbiting camera. No blood, no wounds, no gore.
Sound: heavy impacts, wind, no dialogue.
镜头1: camera pushes in, protagonist draws a weapon, antagonist raises claws.
镜头2: fast exchange, camera orbits.
镜头3: climax, both stay on their sides, protagonist lands ready.
Keep faces and outfits consistent. No text, no numbers, no subtitles, no watermark.

Mẫu trên là định hướng cảnh quay. Rút gọn nếu model bỏ sót hành động; không dùng prompt để thay các tham số API.

Mô tả cảnh hành động không đồ họa

Tránh mô tả đồ họaHướng mô tả an toàn
blood, wound, gore, corpsesparks, black smoke, torn fabric only
Vũng máumurky grey mist, dark viscous puddle
Tấn công gây thương tíchglowing wisps of spirit-light, shadowy aura
Vết cắt trên datearing only the fabric of the sleeve, no blood

Dựng chuỗi nhiều cảnh

  1. Chia câu chuyện thành các cảnh có điểm đầu và cuối rõ.
  2. Giữ cùng mô tả nhân vật, ánh sáng và ảnh tham chiếu.
  3. Tải và kiểm tra từng cảnh trước khi tạo phần tiếp theo.
  4. Ghép cảnh bằng công cụ dựng; mỗi POST vẫn là một tác vụ tính phí riêng.

Khi kết quả chưa đúng

  • Thiếu hành động: giảm số sự kiện trong cùng một cảnh.
  • Nhân vật đổi chỗ: chỉ định rõ trái/phải và giữ bố cục.
  • Mất nhất quán: dùng lại ảnh tham chiếu và mô tả nhận diện.
  • Sai thời lượng: kiểm tra seconds và loại model cố định.
  • Bị từ chối: xem error và chính sách nội dung, không gửi lặp cùng yêu cầu.

Kiểm tra chuyển động bằng lưới khung hình

ffmpeg -i clip.mp4 -vf "fps=1,scale=320:-1,tile=6x5" -frames:v 1 frame_grid.png

Lệnh ffmpeg đọc clip.mp4 trên máy bạn và tạo ảnh lưới, không gọi API. Cần cài ffmpeg trước.

Kiểm tra trước khi chạy

  • Chọn đúng ID model và thời lượng được hỗ trợ.
  • Kiểm tra giá và số dư trước khi tạo.
  • Giữ key ở môi trường máy chủ, không đưa vào trình duyệt công khai.
  • Dùng JSON và URL media mà nhà cung cấp truy cập được.
  • Lưu id, model và request ID để theo dõi.
  • Tra cùng id với ?model=, tăng khoảng nghỉ khi bị giới hạn.
  • Chỉ tải khi completed; kiểm tra tệp MP4 tải về.
  • Không tạo lại tự động khi chưa rõ yêu cầu trước đã được nhận hay chưa.
  • Đối chiếu lỗi và chi phí trong Sử dụng; gửi id cho hỗ trợ khi cần.
Support