Chuyển đến nội dung chính

​
Tổng quan

Việc sinh video là bất đồng bộ. Bạn gửi một yêu cầu, nhận task_id và poll_url, rồi kiểm tra trạng thái định kỳ cho tới khi có kết quả cuối cùng.
Để việc kiểm tra trạng thái đáng tin cậy nhất, hãy dùng chính xác poll_url được trả về từ phản hồi tạo tác vụ.
Nếu phản hồi tạo trả về poll_url, hãy gọi đúng URL đó. Khi nó trỏ tới /v1/tasks/{id}, hãy xem đó là endpoint trạng thái cố định chuẩn.
Đầu ra âm thanh phụ thuộc vào từng model. Trong LemonData, họ Veo 3 sẽ mặc định bật âm thanh nếu bỏ qua output_audio. Khi model hỗ trợ điều khiển âm thanh, hãy dùng output_audio để bật hoặc tắt một cách tường minh. Alias camelCase outputAudio cũng được chấp nhận để tương thích.
Trong môi trường vận hành, nên ưu tiên URL https công khai cho ảnh, video và âm thanh. Các model tương thích vẫn chấp nhận URL data:, nhưng payload base64 lớn sẽ khó retry, kiểm tra và debug hơn.

​
Phần thân yêu cầu

​
model
string
mặc định:"sora-2"
ID model video. Mặc định của API là sora-2. Xem hướng dẫn tạo video để biết ma trận model công khai hiện tại và các khả năng được hỗ trợ.
​
prompt
string
bắt buộc
Mô tả văn bản của video cần tạo. Trường này là bắt buộc với hầu hết model video công khai.
​
operation
string
Tác vụ video cần chạy. Hợp đồng công khai hiện hỗ trợ text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video và motion-control. LemonData có thể suy luận tác vụ từ dữ liệu đầu vào, nhưng với traffic vận hành bạn vẫn nên truyền operation một cách tường minh.
​
image_url
string
URL công khai của ảnh đầu vào cho luồng image-to-video. Để có độ tương thích rộng nhất giữa các model, nên ưu tiên image_url.
​
image
string
Ảnh inline dưới dạng URL data: (ví dụ: data:image/jpeg;base64,...). Các model tương thích có hỗ trợ, nhưng trong môi trường vận hành thì image_url thường ổn định hơn.
​
reference_images
array
Ảnh tham chiếu cho luồng reference-to-video. Bạn có thể truyền tối đa 3 phần tử. Nên ưu tiên URL https công khai; các model tương thích cũng hỗ trợ URL data:.
​
reference_image_type
string
Trường tùy chọn cho những model phân biệt ảnh tham chiếu kiểu asset và style.
​
video_url
string
URL công khai của video nguồn. Trường này cần thiết cho các luồng video-to-video công khai hiện tại và cho các model motion-control.
​
audio_url
string
URL công khai của âm thanh cho các model hỗ trợ audio-to-video.
​
task_id
string
Mã task từ phía provider, dùng trong một số luồng tiếp nối, mở rộng hoặc dẫn xuất.
​
extend_at
integer
Vị trí bắt đầu mở rộng theo đặc thù từng model trong một số luồng video-extension.
​
extend_times
string
Hệ số hoặc số lần lặp theo đặc thù từng model trong một số luồng video-extension.
​
duration
integer
Thời lượng video tính bằng giây. Giá trị hợp lệ phụ thuộc vào model.
​
aspect_ratio
string
Tỷ lệ khung hình, ví dụ 16:9, 9:16 hoặc 1:1.
​
resolution
string
Độ phân giải đầu ra, ví dụ 720p, 1080p hoặc 4k. Mức hỗ trợ phụ thuộc vào model.
​
output_audio
boolean
Công tắc đầu ra âm thanh phụ thuộc vào model. Trong LemonData, họ Veo 3 mặc định dùng true khi bỏ qua trường này. Alias camelCase outputAudio cũng được chấp nhận để tương thích.
​
fps
integer
Số khung hình trên giây (1-120). Chỉ có tác dụng ở những model công khai hỗ trợ điều khiển FPS.
​
negative_prompt
string
Những gì bạn muốn tránh trong video được tạo ra.
​
seed
integer
Seed ngẫu nhiên để có kết quả tái lập.
​
cfg_scale
number
Mức bám theo prompt (0-20) ở những model hỗ trợ kiểu điều khiển này.
​
motion_strength
number
Cường độ chuyển động (0-1) ở những model hỗ trợ trường này.
​
start_image
string
URL ảnh khung hình đầu tiên, hoặc đầu vào ảnh tương thích, cho start-end-to-video.
​
end_image
string
URL ảnh khung hình cuối cùng, hoặc đầu vào ảnh tương thích, cho start-end-to-video.
​
size
string
Bậc kích thước theo đặc thù model trong một số model video tương thích OpenAI.
​
watermark
boolean
Công tắc watermark ở các model có hỗ trợ công khai trường này.
​
effect_type
string
Bộ chọn hiệu ứng theo đặc thù model trong một số luồng chỉnh sửa hoặc hiệu ứng chuyên biệt.
​
user
string
Một định danh duy nhất cho người dùng cuối.

​
Ghi chú tương thích

  • Các trường công khai chuẩn dùng snake_case: reference_images, reference_image_type, và output_audio.
  • Để tương thích, LemonData cũng chấp nhận các alias camelCase là referenceImages, referenceImageType, và outputAudio.
  • Nếu bỏ qua operation, LemonData sẽ suy luận từ dữ liệu đầu vào. Dù vậy, với traffic vận hành vẫn nên truyền operation một cách tường minh.

​
Thực hành tốt cho đầu vào media

  • Với image_url, reference_images, video_url, và audio_url, hãy ưu tiên URL https công khai.
  • Nếu có thể, tránh trộn base64 inline và URL từ xa trong cùng một yêu cầu.
  • Nếu dùng signed URL, hãy giữ thời gian sống đủ dài để bao phủ quá trình retry và tạo task bất đồng bộ.

​
Phản hồi

​
id
string
Mã định danh chuẩn của tác vụ bất đồng bộ. Khi cả id và task_id cùng xuất hiện, hãy xem chúng là cùng một tác vụ.
​
task_id
string
Định danh tác vụ duy nhất để kiểm tra trạng thái.
​
poll_url
string
URL kiểm tra trạng thái được khuyến nghị cho tác vụ này. Hãy dùng đúng đường dẫn này khi kiểm tra trạng thái.
​
status
string
Trạng thái ban đầu: pending.
​
created
integer
Dấu thời gian Unix khi tác vụ được tạo.
​
model
string
Model được sử dụng.
curl -X POST "https://api.lemondata.cc/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "sora-2",
  "created": 1706000000
}

​
Image sang video

response = requests.post(
    "https://api.lemondata.cc/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9"
    }
)

​
Ảnh tham chiếu sang video

Khi model hỗ trợ conditioning bằng ảnh tham chiếu, hãy dùng operation=reference-to-video. Trong hợp đồng công khai của LemonData, dữ liệu tham chiếu được truyền qua reference_images. 
response = requests.post(
    "https://api.lemondata.cc/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

​
Điều khiển khung đầu và cuối

Hãy dùng start_image và end_image để kiểm soát khung hình đầu tiên và cuối cùng. 
response = requests.post(
    "https://api.lemondata.cc/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "prompt": "Smooth transition from day to night",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)

​
Video sang video

Nếu model nhận một video có sẵn làm đầu vào chính, hãy dùng operation=video-to-video. 
response = requests.post(
    "https://api.lemondata.cc/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "topaz-video-upscale",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Upscale the clip while preserving the original motion.",
        "resolution": "1080p"
    }
)

​
Điều khiển chuyển động

Nếu model cần cả ảnh chủ thể lẫn video tham chiếu chuyển động, hãy dùng operation=motion-control. LemonData sẽ chuẩn hóa dạng công khai image_url + video_url về hợp đồng upstream tương ứng. 
response = requests.post(
    "https://api.lemondata.cc/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

​
Tình trạng hỗ trợ audio-to-video và video-extension hiện tại

Hợp đồng công khai của LemonData có chấp nhận audio-to-video và video-extension cho một số luồng đặc thù theo model. Tuy nhiên, trong tập model công khai đang được bật rộng rãi của bản tài liệu này, hiện chưa có model công khai phổ biến nào quảng bá rõ ràng hai khả năng đó. Trước khi tích hợp các luồng này, hãy kiểm tra lại trạng thái mới nhất qua Models API hoặc trang Models.

​
Danh sách model video công khai đang được bật

Danh sách này bám theo inventory model video công khai đang được bật trong bản tài liệu hiện tại. Để có trạng thái mới nhất, hãy dùng Models API.

​
OpenAI

ModelThao tác công khai
sora-2Văn bản sang video, image-to-video
sora-2-proVăn bản sang video, image-to-video
sora-2-pro-storyboardImage-to-video

​
Kuaishou

ModelThao tác công khai
kling-3.0-motion-controlĐiều khiển chuyển động
kling-3.0-videoVăn bản sang video, image-to-video, start-end-to-video
kling-v2.5-turbo-proVăn bản sang video, image-to-video, start-end-to-video
kling-v2.5-turbo-stdVăn bản sang video, image-to-video
kling-v2.6-proVăn bản sang video, image-to-video, start-end-to-video
kling-v2.6-stdVăn bản sang video, image-to-video
kling-v3.0-proVăn bản sang video, image-to-video, start-end-to-video
kling-v3.0-stdVăn bản sang video, image-to-video, start-end-to-video
kling-video-o1-proVăn bản sang video, image-to-video, reference-to-video, start-end-to-video, video-to-video
kling-video-o1-stdVăn bản sang video, image-to-video, reference-to-video, start-end-to-video, video-to-video

​
Google

ModelThao tác công khai
veo3Văn bản sang video, image-to-video
veo3-fastVăn bản sang video, image-to-video
veo3-proVăn bản sang video, image-to-video
veo3.1Văn bản sang video, image-to-video, reference-to-video, start-end-to-video
veo3.1-fastVăn bản sang video, image-to-video, reference-to-video, start-end-to-video
veo3.1-proVăn bản sang video, image-to-video, start-end-to-video

​
ByteDance

ModelThao tác công khai
seedance-1.5-proVăn bản sang video, image-to-video

​
MiniMax

ModelThao tác công khai
hailuo-2.3-fastImage-to-video
hailuo-2.3-proVăn bản sang video, image-to-video
hailuo-2.3-standardVăn bản sang video, image-to-video

​
Alibaba

ModelThao tác công khai
wan-2.2-plusVăn bản sang video, image-to-video
wan-2.5Văn bản sang video, image-to-video
wan-2.6Văn bản sang video, image-to-video, reference-to-video

​
Shengshu

ModelThao tác công khai
viduq2Văn bản sang video, reference-to-video
viduq2-proImage-to-video, reference-to-video, start-end-to-video
viduq2-pro-fastImage-to-video, start-end-to-video
viduq2-turboImage-to-video, start-end-to-video
viduq3-proVăn bản sang video, image-to-video, start-end-to-video
viduq3-turboVăn bản sang video, image-to-video, start-end-to-video

​
xAI

ModelThao tác công khai
grok-imagine-image-to-videoImage-to-video
grok-imagine-text-to-videoVăn bản sang video
grok-imagine-upscaleVideo-to-video

​
Khác

ModelThao tác công khai
topaz-video-upscaleVideo-to-video