API/videos
Tạo video chạy bất đồng bộ: tạo một job, hỏi trạng thái theo id, rồi tải MP4 về khi hoàn tất.
https://api.framewharf.com/v1/videosAuthorization: Bearer sk-your_api_keyĐể tạo và sửa video bằng Gemini Omni, dùng POST /v1/interactions.
POST /v1/videos nhận model, prompt và seconds (1–15, mặc định 8). Một giá trị size (1280x720) đặt cùng lúc độ phân giải và tỉ lệ khung hình, hoặc bạn đặt riêng từng thứ: độ phân giải qua extra_body.resolution: 480p (mặc định), 720p hoặc 1080p; tỉ lệ khung hình qua extra_body.aspect_ratio (16:9 mặc định, 1:1, 9:16…).
curl "https://api.framewharf.com/v1/videos" \
-H "Authorization: Bearer sk-your_api_key" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-1.5-lite",
"prompt": "Sóng vỗ vào bờ đá lúc hoàng hôn",
"seconds": "6",
"extra_body": { "resolution": "720p" }
}'Request trả về một job ngay lập tức — giữ lại id để hỏi trạng thái:
{
"id": "video_bGl0ZWxsbTpjdXN0b21fbGxt...",
"object": "video",
"status": "queued",
"model": "grok-imagine-video-1.5-lite",
"seconds": "6",
"size": "720p"
}Mỗi video dưới đây được tạo từ endpoint này, mỗi video một job, kèm prompt đã tạo ra nó.
Để tạo chuyển động cho một ảnh bạn đã có (ảnh sang video), thêm trường image chứa URL công khai hoặc data URL base64; khi có ảnh, prompt là tùy chọn:
{
"model": "grok-imagine-video-1.5-lite",
"prompt": "Cho con thuyền trong ảnh trôi chầm chậm về phía chân trời",
"seconds": "6",
"image": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." }
}Kéo thanh trượt: bên trái là ảnh tĩnh đưa vào, bên phải là video mà một request tạo ra từ ảnh đó.

Nhiều ảnh có thể cùng dẫn dắt một clip thay vì ghim khung hình đầu tiên: extra_body.reference_images nhận một danh sách, được gọi trong prompt là <IMAGE_0> theo đúng thứ tự bạn gửi, còn extra_body.last_frame ghim khung hình kết thúc.
{
"model": "grok-imagine-video-1.5-lite",
"prompt": "Nhân vật trong <IMAGE_0> đi ngang qua căn phòng trong <IMAGE_1>",
"seconds": "6",
"extra_body": {
"reference_images": [
{ "url": "https://example.com/character.jpg" },
{ "url": "https://example.com/room.jpg" }
],
"last_frame": { "url": "https://example.com/final-shot.jpg" }
}
}Để ghim cả những khung hình giữa clip, gửi extra_body.keyframes — tối đa bốn ảnh, mỗi ảnh kèm timestamp tính bằng giây, nằm hẳn bên trong clip. Để nhân vật cất tiếng bằng một giọng có sẵn, gửi extra_body.reference_audios — tối đa ba giọng, gọi trong prompt là <AUDIO_0> theo thứ tự bạn gửi.
{
"model": "grok-imagine-video-1.5-lite",
"prompt": "Một cái cây qua bốn mùa, <AUDIO_0> khẽ nói: mùa xuân đến rồi",
"seconds": "8",
"image": { "url": "https://example.com/start.jpg" },
"extra_body": {
"resolution": "720p",
"keyframes": [
{ "image_url": "https://example.com/middle.jpg", "timestamp": 4 }
],
"last_frame": { "url": "https://example.com/end.jpg" },
"reference_audios": [{ "voice_id": "eve" }]
}
}Clip được dẫn dắt bằng ảnh tham chiếu, khung hình ghim sẵn hoặc giọng tham chiếu có độ phân giải tối đa 720p. Đây là tính năng của các mô hình mới hơn; mô hình không hỗ trợ tính năng nào, hoặc request mang một trường không có trong tài liệu, sẽ bị từ chối với thông báo rõ ràng thay vì bị bỏ qua.
Gọi GET /v1/videos/{id} vài giây một lần cho đến khi job ra khỏi trạng thái đang xử lý. Một video thường xong trong khoảng vài chục giây đến vài phút, tùy độ dài và độ phân giải.
curl "https://api.framewharf.com/v1/videos/video_bGl0ZWxsbTpjdXN0b21fbGxt..." \
-H "Authorization: Bearer sk-your_api_key"Khi status là completed, tải MP4 về qua GET /v1/videos/{id}/content. Yêu cầu này chuyển hướng tới một đường dẫn tải tạm thời, có hiệu lực trong khoảng 30 phút (cũng có trong trường url của phản hồi), nên client cần đi theo chuyển hướng. Hãy tải và lưu tệp ở phía bạn ngay khi job hoàn tất — job cũ sẽ hết hạn và không thể tải lại.
curl -L "https://api.framewharf.com/v1/videos/video_bGl0ZWxsbTpjdXN0b21fbGxt.../content" \
-H "Authorization: Bearer sk-your_api_key" \
-o video.mp4POST /v1/videos/edits nhận video.id của một job đã hoàn tất và một prompt mô tả thay đổi; phần còn lại của cảnh được giữ nguyên.
curl "https://api.framewharf.com/v1/videos/edits" \
-H "Authorization: Bearer sk-your_api_key" \
-H "Content-Type: application/json" \
-d '{
"video": { "id": "video_bGl0ZWxsbTpjdXN0b21fbGxt..." },
"prompt": "Biến cảnh ban ngày thành cảnh đêm dưới ánh đèn đường"
}'Một lần sửa không nhận độ dài hay độ phân giải: kết quả kế thừa cả hai từ video nguồn — tối đa 720p và tối đa 8,7 giây — và bạn nhận về một id job mới để hỏi trạng thái và tải về giống hệt một job mới tạo. Chỉ video tạo bằng mô hình ghi bên dưới mới sửa được.
POST /v1/videos/extensions nối dài một video đã xong từ khung hình cuối của nó; seconds (2–10, mặc định 6) là độ dài của phần mới, không phải của kết quả.
curl "https://api.framewharf.com/v1/videos/extensions" \
-H "Authorization: Bearer sk-your_api_key" \
-H "Content-Type: application/json" \
-d '{
"video": { "id": "video_bGl0ZWxsbTpjdXN0b21fbGxt..." },
"prompt": "Máy quay tiếp tục lùi ra xa và con thuyền rời khỏi khung hình",
"seconds": "6"
}'Id trả về có thể tiếp tục được nối dài hoặc sửa, nên một chuỗi cảnh dài được dựng lên từng đoạn một. Chỉ video tạo bằng mô hình ghi bên dưới mới sửa hoặc nối dài được.
seedance-2.5 dùng chung các bước tạo, hỏi trạng thái và tải về ở trên, với bộ tham số riêng: prompt là bắt buộc; seconds từ 4 đến 30 (mặc định 5), hoặc -1 để mô hình tự chọn độ dài; resolution 480p, 720p (mặc định) hoặc 1080p; aspect_ratio 16:9 (mặc định), 4:3, 1:1, 3:4, 9:16, 21:9 hoặc adaptive (mô hình tự chọn tỉ lệ); generate_audio (mặc định bật, tạo kèm âm thanh) và seed.
Để mở đầu và kết thúc clip bằng ảnh của bạn, gửi image làm khung hình đầu và, nếu muốn, last_frame làm khung hình cuối — URL công khai hoặc data URL JPEG/PNG/WebP. Khi có khung đầu, tỉ lệ khung hình đi theo ảnh nên đừng gửi aspect_ratio. Với return_last_frame, trạng thái của job đã xong có thêm đường dẫn tạm tới khung hình cuối của video, trong last_frame_url.
{
"model": "seedance-2.5",
"prompt": "Máy quay lướt qua căn phòng rồi dừng ở ô cửa sổ",
"seconds": "5",
"image": { "url": "https://example.com/start.jpg" },
"extra_body": {
"resolution": "720p",
"last_frame": { "url": "https://example.com/end.jpg" },
"return_last_frame": true
}
}Thay cho khung hình, bạn có thể dẫn dắt clip bằng tham chiếu: reference_images (tối đa 30 ảnh), reference_videos (tối đa 10 video qua URL, tổng cộng không quá 30 giây) và reference_audios (tối đa 10 tệp MP3/WAV, qua URL hoặc data URL). Nhắc tới chúng trong prompt theo thứ tự bạn gửi; có thể chỉ gửi audio. Khung hình và tham chiếu không đi chung một request.
{
"model": "seedance-2.5",
"prompt": "Người trong ảnh nhảy theo động tác của video tham chiếu, theo nhịp bản nhạc",
"seconds": "8",
"extra_body": {
"resolution": "720p",
"aspect_ratio": "9:16",
"reference_images": [{ "url": "https://example.com/dancer.jpg" }],
"reference_videos": [{ "url": "https://example.com/moves.mp4" }],
"reference_audios": [{ "url": "https://example.com/beat.mp3" }]
}
}Khi prompt yêu cầu sửa chính video tham chiếu (đổi phong cách, thay một vật thể…), mô hình giữ tỉ lệ và độ dài của video đó — hãy gửi aspect_ratio: "adaptive" và seconds: -1, nếu không job sẽ thất bại và credit được hoàn lại. Video gốc dài từ 4 đến 30 giây.
{
"model": "seedance-2.5",
"prompt": "Vẽ lại toàn bộ cảnh trong video theo phong cách màu nước",
"seconds": -1,
"extra_body": {
"resolution": "720p",
"aspect_ratio": "adaptive",
"reference_videos": [{ "url": "https://example.com/clip.mp4" }]
}
}Credit được trừ khi job được tạo: số giây yêu cầu nhân với đơn giá mỗi giây của độ phân giải đó. Mô hình video được mở theo từng API key — GET /v1/models với key của bạn liệt kê đúng những mô hình bạn gọi được; nhắn Framewharf nếu bạn cần thêm quyền truy cập.