Tạo video

Tìm kiếm /

Các mô hình video trả lời dưới dạng tác vụ chứ không phải một phản hồi duy nhất. POST /v1/videos trả về mã tác vụ kèm "status": "queued", còn GET /v1/videos/{task_id} báo tiến độ cho đến khi tác vụ chuyển sang completed hoặc failed. Khi hoàn tất, tệp kết quả là URL đã ký nằm trong metadata.url; URL này mang tham số Expires, vì vậy hãy tải tệp về thay vì lưu lại liên kết. Tác vụ thất bại mang mã lỗi và thông báo của nhà cung cấp trong error.code và error.message, thường là đủ để biết yêu cầu thiếu trường nào. POST /v1/video/generations đi tới cùng một handler, dành cho ứng dụng khách đã viết theo đường dẫn đó.

POST /v1/videos

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "the cat turns and walks toward the camera",
    "input_reference": "https://example.com/first-frame.jpg",
    "size": "1280*720",
    "duration": 5
  }'

# {"id":"task_9f2c...","task_id":"task_9f2c...","object":"video",
#  "model":"wan2.7-i2v","status":"queued","progress":0}

GET /v1/videos/{task_id}

curl https://api.chinaapi.ai/v1/videos/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"id":"task_9f2c...","object":"video","model":"wan2.7-i2v",
#  "status":"completed","progress":100,
#  "metadata":{"url":"https://.../output.mp4?Expires=..."}}

Văn bản thành video

wan2.7-t2v

Chỉ model và prompt là bắt buộc. Nếu thiếu size và duration, cổng sẽ gửi 1280*720 trong năm giây.

Ảnh thành video

wan2.7-i2v

Làm ảnh tĩnh chuyển động. input_reference nhận URL ảnh công khai và trở thành khung hình đầu tiên; hãy gửi kèm size và duration.

Tham chiếu thành video

wan2.7-r2v

Tạo video từ tư liệu tham chiếu. input_reference nhận một ảnh tham chiếu; muốn gửi nhiều ảnh thì dùng images, và video_url thêm một video tham chiếu — các tham chiếu được tính chung, tối đa năm. Đừng gửi input_reference cùng images, vì cổng chỉ giữ lại input_reference.

Chỉnh sửa video

wan2.7-videoedit

Chỉnh sửa một video có sẵn theo prompt. video_url nhận video nguồn, dài từ 2 đến 10 giây ở định dạng MP4 hoặc MOV, và size quyết định đầu ra.

Video 30 giây

doubao-seedance-2-5-260628

Ảnh tham chiếu đặt trong images, còn input_reference nhận một ảnh; gửi cả hai thì cả hai đều được giữ. Độ dài đặt trong seconds hoặc duration, còn tham số của nhà cung cấp đặt trong metadata, nơi resolution chỉ nhận 480p hoặc 720p.

Seedance 2.0

doubao-seedance-2-0-260128

Cùng dạng yêu cầu với doubao-seedance-2-5-260628, kể cả quy tắc role cho metadata.content. doubao-seedance-2-0-fast-260128 và doubao-seedance-2-0-mini-260615 đánh đổi chất lượng lấy tốc độ và chi phí, và dòng 2.0 cần ít nhất một tham chiếu ảnh hoặc video, trong khi 2.5 còn nhận riêng âm thanh.

Kling 3.0

kling-v3

Khung đầu đặt trong image; dòng này không bao giờ đọc input_reference. mode mặc định là std và duration mặc định 5 giây. metadata mang phần còn lại: image_tail cho khung kết, sound nhận on hoặc off (mặc định off), cùng negative_prompt, cfg_scale và camera_control.

Bậc tiết kiệm

kling-3.0-turbo

Gửi prompt cho văn bản thành video, hoặc thêm image và cổng sẽ dựng mảng contents mà phía trên yêu cầu. Phần kích thước nằm dưới metadata.settings: resolution là 720p hoặc 1080p, duration từ 3 đến 15 giây, và aspect_ratio là 16:9, 9:16 hoặc 1:1. Âm thanh luôn có và không có công tắc tắt.

Tham chiếu nhiều ảnh

kling-v3-omni

Tạo video dựa trên nhiều ảnh tham chiếu cùng lúc. Mọi tham số đều nằm trong metadata, và không có trường resolution — bậc chất lượng chính là mode. Xem ví dụ đầy đủ bên dưới.

Âm thanh gốc

MiniMax-H3

Nhận đúng các trường của cổng rồi tự dựng payload gửi lên: image hoặc input_reference thành khung đầu, images thành ảnh tham chiếu, và video_url thành video tham chiếu. size chọn 768P hoặc 2K, còn duration là số nguyên từ 4 đến 15. Yêu cầu chỉ có văn bản cần metadata.ratio tường minh khác adaptive.

Hailuo

MiniMax-Hailuo-2.3

Cùng với MiniMax-Hailuo-2.3-Fast và MiniMax-Hailuo-02. Nhóm này chỉ đọc prompt, duration và size ở cấp cao nhất; mọi ảnh đều phải đi qua metadata, dưới dạng first_frame_image, last_frame_image hoặc subject_reference.

Bậc 480P

happyhorse-1.1-t2v

Cùng với happyhorse-1.1-i2v và happyhorse-1.1-r2v. Các trường giống họ wan2.7 — prompt, input_reference, size, duration — và 480P ở đây có giá, nên 832*480 được chấp nhận trong khi wan2.7 từ chối. Nhiều tham chiếu thì đặt vào metadata.input.media, vì cơ chế tự dựng mà trường images kích hoạt chỉ dành riêng cho wan2.7-r2v.

Mẹo Viết size là chiều rộng và chiều cao nối bằng dấu sao, ví dụ 1280*720. Không dùng chữ x: 832x480 sẽ trả về invalid size: 832x480, example: 1920*1080. duration là số giây nguyên. Với wan2.7-i2v, wan2.7-r2v và wan2.7-videoedit, cổng gộp size thành bậc độ phân giải và phía trên chỉ có hai bậc, nên hãy gửi 1280*720 cho 720P hoặc 1920*1080 cho 1080P. Kích thước 480P như 832*480 không có giá ở ba mô hình này nên hoặc bị từ chối ngay, hoặc được nhận rồi thất bại ở phía trên với InvalidParameter; tác vụ thất bại sẽ được hoàn tiền, nhưng dù thế nào thì lượt gọi đó cũng mất không. wan2.7-t2v nhận giá trị đúng như bạn viết.

Mẹo Họ Kling đọc tỉ lệ khung hình từ size qua một bảng cố định viết kích thước bằng chữ x — 1280x720, 1920x1080, 720x1280, 1080x1920, 1024x1024, 512x512 — và bất cứ giá trị nào ngoài bảng đều thành 1:1 mà không báo lỗi. Vì vậy gửi dạng dấu sao 1280*720 cho kling-v3 sẽ trả về video vuông chứ không phải một lời phàn nàn; hãy đặt thẳng metadata.aspect_ratio khi bố cục là điều quan trọng.

Mẹo MiniMax-Hailuo-2.3, MiniMax-Hailuo-2.3-Fast và MiniMax-Hailuo-02 lặng lẽ bỏ các trường cấp cao nhất image, input_reference, images và video_url: yêu cầu vẫn thành công, nhưng chạy như văn bản thành video và bị tính tiền theo đúng kiểu đó. Hãy đặt ảnh vào metadata.first_frame_image, thêm metadata.last_frame_image cho khung kết, và dùng metadata.subject_reference cho tham chiếu nhân vật. MiniMax-H3 là ngoại lệ của nhóm này và có đọc các trường cấp cao nhất.

kling-v3-omni · multi-image reference

curl https://api.chinaapi.ai/v1/video/generations \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "the character from the references walks through a neon-lit street",
    "metadata": {
      "image_list": [
        {"image_url": "https://example.com/character.jpg"},
        {"image_url": "https://example.com/outfit.jpg"},
        {"image_url": "https://example.com/scene.jpg"}
      ],
      "mode": "std",
      "duration": "5",
      "aspect_ratio": "16:9",
      "sound": "off"
    }
  }'

GET /v1/video/generations/{task_id}

curl https://api.chinaapi.ai/v1/video/generations/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"code":"success",
#  "data":{"task_id":"task_9f2c...","status":"SUCCESS",
#          "progress":"100%","fail_reason":"",
#          "result_url":"https://.../output.mp4"}}

Mẹo Ảnh tham chiếu không mang type; trường này chỉ tồn tại để đánh dấu first_frame hoặc end_frame, và aspect_ratio là bắt buộc khi không có khung đầu. mode là bậc chất lượng — std, pro hoặc 4k — và mặc định phía trên là pro, tính tiền gấp 1,33 lần giá niêm yết, còn 4k gấp 5 lần; hãy gửi mode tường minh để số tiền đúng như bạn dự tính. duration là chuỗi từ "3" đến "15" và sound mặc định là off. Video tham chiếu đặt trong video_list và bắt buộc phải có "refer_type": "feature": chế độ chỉnh sửa base tính tiền theo độ dài video bạn cung cấp, không thể định giá trước khi gửi, nên bị từ chối. Ảnh tham chiếu cũng có kích thước tối thiểu ở phía trên: một tệp cỡ biểu tượng vẫn gửi được nhưng sẽ làm tác vụ thất bại với Image pixel is invalid; tác vụ thất bại được hoàn tiền, nhưng lượt gọi đó mất không.

Mẹo Hai đường dẫn trả kết quả theo hai dạng khác nhau. GET /v1/videos/{task_id} trả theo định dạng video của OpenAI, trong đó tệp nằm ở metadata.url và tiến độ là một con số. GET /v1/video/generations/{task_id} trả {"code": "success", "data": {…}}, trong đó tệp nằm ở data.result_url, data.status là một từ viết hoa như SUCCESS hoặc FAILURE, data.progress là chuỗi như "100%", và lỗi được giải thích trong data.fail_reason. Hãy hỏi trạng thái ở đúng đường dẫn bạn đã gửi.

doubao-seedance-2-5-260628 · first frame

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "the subject slowly turns toward the camera",
    "images": ["https://example.com/first-frame.jpg"],
    "seconds": "5",
    "metadata": {"resolution": "480p"}
  }'

doubao-seedance-2-5-260628 · reference mode

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "keep the subject from the reference image",
    "seconds": "5",
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "content": [
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/reference.jpg"},
          "role": "reference_image"
        }
      ]
    }
  }'

Mẹo Ảnh không có role được đọc là khung đầu chứ không phải tham chiếu: đầu ra theo tỉ lệ khung của ảnh đó, gửi kèm ratio sẽ bị từ chối với InvalidParameter.TaskTypeConstraint, và seconds bằng 2 cũng bị từ chối ở chế độ này, còn 5 thì được. generate_audio mặc định là true ở phía trên, nên tệp trả về có kèm âm thanh trừ khi bạn đặt false trong metadata. Gắn role cho từng phần tử của metadata.content để dùng đầy đủ chế độ tham chiếu — tối đa 30 ảnh, 10 video và 10 đoạn âm thanh, cho phép chỉ nhập âm thanh, và 30 giây liền mạch — nơi ratio được chấp nhận.