Endpoints

Videos

Video Generation

POST /v1/videos

Gửi request tạo video (asynchronous). Trả về job ID để poll trạng thái.

Request

$$ curl -X POST https://api.staging.tram.ai.vn/v1/videos \
>>   -H "Content-Type: application/json" \
>>   -H "Authorization: Bearer $TRAM_AI_API_KEY" \
>>   -d '{
>>     "model": "veo-3.1",
>>     "prompt": "A golden retriever playing fetch on a sunny beach",
>>     "seconds": 4
>>   }'

Parameters

ParameterTypeRequiredMô tả
modelstringYesModel ID. Lấy từ GET /v1/models hoặc /public/models, chọn model có mode: "video" (ví dụ: veo-3.1, seedance-2.0-mini)
promptstringYesText mô tả video (tối đa 10.000 ký tự)
secondsintegerNoThời lượng video (giây). Phải nằm trong allowedDurations của model
sizestringNoKích thước / tỷ lệ khung hình (ví dụ: 1280x720, 16:9)
input_referencestring | objectNoẢnh first frame cho image-to-video. Xem định dạng bên dưới
last_framestring | objectNoẢnh last frame — tạo video chuyển tiếp từ first frame đến last frame. Xem Last frame. Chỉ model Seedance
reference_imagesstring[]NoDanh sách URL hoặc data URI ảnh tham khảo (tối đa 9 ảnh). Dùng để hướng dẫn phong cách/nội dung. Chỉ model Seedance. Không dùng cùng input_reference
resolutionstringNoĐộ phân giải: 480p, 720p, 1080p, 4k. Mặc định 720p. Chỉ model Seedance
seedintegerNoSeed để tạo kết quả có thể tái tạo
generate_audiobooleanNoTạo âm thanh đồng bộ. Mặc định true trên Seedance
watermarkbooleanNoĐóng dấu “AI-generated” vào video (watermark do provider thêm để đánh dấu nội dung do AI tạo). Chỉ model Seedance
return_last_framebooleanNoTrả URL ảnh frame cuối trong response khi hoàn tất. Chỉ model Seedance
parametersobjectNoTham số pass-through đến provider

input_reference

Dùng để gửi ảnh đầu vào khi muốn tạo video từ ảnh (image-to-video). Hỗ trợ 2 định dạng:

Dạng string — Data URI hoặc URL:

1{
2  "input_reference": "data:image/png;base64,iVBORw0KGgo..."
3}

Dạng object — Base64 kèm MIME type:

1{
2  "input_reference": {
3    "bytesBase64Encoded": "iVBORw0KGgo...",
4    "mimeType": "image/png"
5  }
6}

Kích thước tối đa: 10 MB. Định dạng ảnh hỗ trợ: PNG, JPEG, WebP.

last_frame

Chỉ hỗ trợ với model Seedance. Dùng để tạo video chuyển tiếp từ ảnh đầu (first frame) đến ảnh cuối (last frame). Khi dùng last_frame, phải gửi kèm input_reference (first frame).

Hỗ trợ cùng 2 định dạng như input_reference (data URI string hoặc object).

1{
2  "model": "seedance-2.0-mini",
3  "prompt": "Smooth transition from day to night",
4  "seconds": 4,
5  "size": "16:9",
6  "input_reference": "data:image/png;base64,<first-frame-base64>",
7  "last_frame": "data:image/png;base64,<last-frame-base64>"
8}

reference_images

Chỉ hỗ trợ với model Seedance. Danh sách URL hoặc data URI ảnh tham khảo (tối đa 9 ảnh) để hướng dẫn phong cách và nội dung video.

Không dùng reference_images cùng lúc với input_reference. Request sẽ bị từ chối khi gửi cả hai.

1{
2  "model": "seedance-2.0-mini",
3  "prompt": "Product rotating on turntable, matching reference style",
4  "seconds": 4,
5  "size": "16:9",
6  "resolution": "1080p",
7  "reference_images": [
8    "https://storage.example.com/ref1.jpg",
9    "https://storage.example.com/ref2.jpg"
10  ],
11  "generate_audio": false
12}

Ràng buộc thời lượng

Mỗi model có danh sách allowedDurations riêng. Ví dụ:

ModelThời lượng cho phép (giây)
veo-3.14, 6, 8
seedance-2.0-mini4–15

Nếu seconds không nằm trong danh sách cho phép của model, request sẽ bị từ chối.

Response (202 Accepted)

1{
2  "id": "c0845e6f-a159-4238-a172-c134a0e9b8fb",
3  "object": "video.job",
4  "status": "submitted",
5  "model": "veo-3.1",
6  "created_at": 1782886429
7}

Video Status

GET /v1/videos/{id}

Poll trạng thái của một video job.

Request

$$ curl https://api.staging.tram.ai.vn/v1/videos/c0845e6f-a159-4238-a172-c134a0e9b8fb \
>>   -H "Authorization: Bearer $TRAM_AI_API_KEY"

Response — Processing

1{
2  "id": "c0845e6f-a159-4238-a172-c134a0e9b8fb",
3  "object": "video.job",
4  "status": "processing",
5  "model": "veo-3.1",
6  "created_at": 1782886429
7}

Response — Completed

1{
2  "id": "c0845e6f-a159-4238-a172-c134a0e9b8fb",
3  "object": "video.job",
4  "status": "completed",
5  "model": "veo-3.1",
6  "created_at": 1782886429,
7  "completed_at": 1782886475,
8  "result": {
9    "duration_seconds": 4
10  },
11  "usage": {
12    "duration_seconds": 4,
13    "cost_vnd": 42346
14  }
15}

Response — Failed

1{
2  "id": "c0845e6f-a159-4238-a172-c134a0e9b8fb",
3  "object": "video.job",
4  "status": "failed",
5  "model": "veo-3.1",
6  "created_at": 1782886429,
7  "error": {
8    "message": "Video generation failed."
9  }
10}

Job statuses

StatusMô tả
submittedJob đã được gửi và đang trong hàng đợi
processingVideo đang được tạo
completedVideo đã sẵn sàng để tải
failedQuá trình tạo thất bại
expiredJob đã hết hạn trước khi hoàn tất

List Videos

GET /v1/videos

Liệt kê các video job.

Request

$$ curl "https://api.staging.tram.ai.vn/v1/videos?status=completed&limit=10" \
>>   -H "Authorization: Bearer $TRAM_AI_API_KEY"

Query Parameters

ParameterTypeRequiredMô tả
statusstringNoLọc theo trạng thái: submitted, processing, completed, failed, expired
limitintegerNoSố job tối đa (1–100, mặc định 20)

Response

1{
2  "object": "list",
3  "data": [
4    {
5      "id": "c0845e6f-...",
6      "object": "video.job",
7      "status": "completed",
8      "model": "veo-3.1",
9      "created_at": 1782886429,
10      "completed_at": 1782886475,
11      "result": { "duration_seconds": 4 },
12      "usage": { "duration_seconds": 4, "cost_vnd": 42346 }
13    }
14  ]
15}

Video Content

GET /v1/videos/{id}/content

Tải video đã hoàn tất. Chỉ khả dụng khi job status là completed.

Request

$$ curl -o output.mp4 \
>>   https://api.staging.tram.ai.vn/v1/videos/c0845e6f-a159-4238-a172-c134a0e9b8fb/content \
>>   -H "Authorization: Bearer $TRAM_AI_API_KEY"

Response

Trả về raw video bytes với Content-Type: video/mp4.

Video hết hạn ở provider sau khoảng 24–48 giờ. Hãy tải video ngay sau khi job hoàn tất.

Billing

Video được tính phí theo giây video × giá mỗi giây (VND). Sử dụng cơ chế deferred-settle:

  • Khi gửi: hold trên tài khoản cho chi phí ước tính tối đa
  • Khi hoàn tất: tính phí thực tế, giải phóng hold
  • Khi thất bại/hết hạn: giải phóng hold, không tính phí

Chi phí hiển thị trong trường usage.cost_vnd của response khi job completed.