建立影片

概覽

影片生成是非同步的。你提交請求後，會收到一個任務 ID 與 poll_url，之後再透過輪詢取得結果。

建立回應會返回規範非同步識別 id，並通常同時回傳 task_id。請優先輪詢 poll_url；如果需要固定狀態入口，請使用 GET /v1/tasks/{id}。

如果建立回應返回 poll_url，請直接使用該 URL。若它指向 /v1/tasks/{id}，請將其視為規範的固定狀態查詢入口。

為了獲得最可靠的輪詢行為，請嚴格使用建立請求回傳的 poll_url。

音訊輸出是否開啟取決於具體模型。在 LemonData 中，Veo 3 家族在省略 output_audio 時，預設會以開啟音訊的方式處理；當模型支援音訊控制時，可透過 output_audio 明確切換。為了相容舊有請求，也接受 camelCase 別名 outputAudio。

在生產環境中，建議優先使用可從公網直接存取的 https URL 作為圖片、影片與音訊輸入。相容模型仍支援內嵌 data: URL，但大體積 base64 在重試、觀測與除錯時通常較不友善。

請求主體

model

string

預設值:"sora-2"

影片模型 ID。API 預設值為 sora-2。如需查看目前的公開影片模型矩陣與支援能力，請參閱影片生成指南。

prompt

string

必填

要生成影片的文字描述。大多數公開影片模型都需要這個欄位。

operation

string

要執行的影片操作。公開契約支援 text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension、audio-to-video 與 motion-control。LemonData 可以根據輸入自動推斷操作，但在生產環境中仍建議明確傳入 operation。

image_url

string

用於圖生影片的起始圖片 URL。為了獲得最廣泛的跨模型相容性，建議優先使用 image_url。

image

string

以內嵌 data URL 形式提供的圖片（例如 data:image/jpeg;base64,...）。相容模型支援這種方式，但 image_url 的相容性更廣。

reference_images

array

用於參考圖生影片的參考圖片輸入。最多可提供 3 張。建議優先使用公網可存取的 https URL；相容模型也支援內嵌 data: URL。

reference_image_type

string

可選的參考圖片角色欄位，用於區分支援 asset 與 style 兩種參考圖類型的模型。

video_url

string

來源影片的公網 URL。當前公開的 video-to-video 流程，以及 motion-control 模型都需要這個欄位。

audio_url

string

提供給 audio-to-video 模型使用的公網音訊 URL。

task_id

string

某些續寫、延展或衍生流程所使用的 Provider 側任務 ID。

extend_at

integer

某些 video-extension 流程使用的模型側延展起點參數。

extend_times

string

某些 video-extension 流程使用的模型側延展次數或倍率參數。

duration

integer

影片時長（秒），依模型而定。

aspect_ratio

string

長寬比，例如 16:9、9:16、1:1。

resolution

string

輸出解析度，例如 720p、1080p、4k，具體支援情況取決於模型。

output_audio

boolean

模型相關的音訊輸出開關。在 LemonData 中，Veo 3 家族在省略這個欄位時預設按 true 處理；其他公開影片模型則依照各自治理後的預設行為執行。為了相容舊有請求，也接受 camelCase 別名 outputAudio。

fps

integer

每秒影格數（1-120），僅在模型公開支援 FPS 控制時生效。

negative_prompt

string

希望在影片生成過程中避免出現的內容。

seed

integer

用於可重現生成結果的隨機種子。

cfg_scale

number

提示詞遵循強度（0-20），僅在公開模型支援此控制項時生效。

motion_strength

number

動作強度（0-1），僅在公開模型支援這個欄位時生效。

start_image

string

start-end-to-video 中使用的起始幀圖片 URL 或相容圖片輸入。

end_image

string

start-end-to-video 中使用的結束幀圖片 URL 或相容圖片輸入。

size

string

某些 OpenAI 相容影片模型使用的尺寸檔位參數。

watermark

boolean

某些模型會暴露出的浮水印開關。

effect_type

string

某些特效或編輯流程所使用的模型側效果選擇器。

user

string

終端使用者的唯一識別碼。

相容說明

公開契約中的規範欄位採用 snake_case：reference_images、reference_image_type、output_audio。
為了相容既有呼叫，LemonData 也接受 camelCase 別名 referenceImages、referenceImageType 與 outputAudio。
若省略 operation，LemonData 會根據輸入自動推斷操作；但在生產環境中，仍建議顯式傳入。

輸入最佳實踐

對於 image_url、reference_images、video_url 與 audio_url，建議優先使用公網可存取的 https URL。
盡量避免在同一個請求中混用內嵌 base64 與遠端 URL；統一採用同一種表示方式更容易排錯與重試。
如果使用簽名 URL，請確保有效期足以覆蓋重試窗口與非同步任務建立流程。

回應

string

規範非同步任務 ID。

task_id

string

用於輪詢的唯一任務識別碼。

poll_url

string

此任務建議使用的輪詢 URL。查詢狀態時請使用這個精確路徑。

status

string

初始狀態：pending。

created

integer

建立任務時的 Unix 時間戳。

model

string

所使用的模型。

video_url

string

結果已就緒時可直接使用的影片 URL。

video

object

可用時返回單一影片物件，包含 url、duration、width 與 height。

videos

array

當上游返回多個輸出時，可能出現影片陣列。

error

string

任務失敗時返回的錯誤訊息或結構化錯誤物件。

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
}

圖生影片

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"
    }
)

參考圖生影片

當模型支援專門的參考圖條件控制時，請使用 operation=reference-to-video。在 LemonData 的公開契約中，參考圖統一透過 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 and palette while adding subtle 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"
    }
)

首尾幀控制

使用 start_image 與 end_image 控制首幀與尾幀：

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"
    }
)

影片轉影片

當模型接受現有影片作為主要輸入時，請使用 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"
    }
)

動作控制

當模型同時需要主體圖片與動作參考影片時，請使用 operation=motion-control。LemonData 會把公開的 image_url + video_url 請求形態映射到上游的動作控制契約。

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"
    }
)

Audio-to-Video 與 Video Extension 的目前可用性

LemonData 的公開契約接受 audio-to-video 與 video-extension 這兩個操作值，用於模型特定流程；但在目前這版文件對應的「通用啟用」公開影片模型清單中，並沒有一個廣泛啟用的公開模型明確對外提供這兩項能力。接入前請先透過 Models API 或模型頁面確認即時可用性。

目前啟用的公開影片模型

此清單已與目前這個文件建置版本中的公開影片模型啟用清單對齊。若要取得最新狀態，請使用 Models API。

OpenAI

Model	公開操作
`sora-2`	文生影片、圖生影片
`sora-2-pro`	文生影片、圖生影片
`sora-2-pro-storyboard`	圖生影片

Kuaishou

Model	公開操作
`kling-3.0-motion-control`	動作控制
`kling-3.0-video`	文生影片、圖生影片、首尾幀生影片
`kling-v2.5-turbo-pro`	文生影片、圖生影片、首尾幀生影片
`kling-v2.5-turbo-std`	文生影片、圖生影片
`kling-v2.6-pro`	文生影片、圖生影片、首尾幀生影片
`kling-v2.6-std`	文生影片、圖生影片
`kling-v3.0-pro`	文生影片、圖生影片、首尾幀生影片
`kling-v3.0-std`	文生影片、圖生影片、首尾幀生影片
`kling-video-o1-pro`	文生影片、圖生影片、參考圖生影片、首尾幀生影片、影片轉影片
`kling-video-o1-std`	文生影片、圖生影片、參考圖生影片、首尾幀生影片、影片轉影片

Google

Model	公開操作
`veo3`	文生影片、圖生影片
`veo3-fast`	文生影片、圖生影片
`veo3-pro`	文生影片、圖生影片
`veo3.1`	文生影片、圖生影片、參考圖生影片、首尾幀生影片
`veo3.1-fast`	文生影片、圖生影片、參考圖生影片、首尾幀生影片
`veo3.1-pro`	文生影片、圖生影片、首尾幀生影片

ByteDance

Model	公開操作
`seedance-1.5-pro`	文生影片、圖生影片

MiniMax

Model	公開操作
`hailuo-2.3-fast`	圖生影片
`hailuo-2.3-pro`	文生影片、圖生影片
`hailuo-2.3-standard`	文生影片、圖生影片

Alibaba

Model	公開操作
`wan-2.2-plus`	文生影片、圖生影片
`wan-2.5`	文生影片、圖生影片
`wan-2.6`	文生影片、圖生影片、參考圖生影片

Shengshu

Model	公開操作
`viduq2`	文生影片、參考圖生影片
`viduq2-pro`	圖生影片、參考圖生影片、首尾幀生影片
`viduq2-pro-fast`	圖生影片、首尾幀生影片
`viduq2-turbo`	圖生影片、首尾幀生影片
`viduq3-pro`	文生影片、圖生影片、首尾幀生影片
`viduq3-turbo`	文生影片、圖生影片、首尾幀生影片

xAI

Model	公開操作
`grok-imagine-image-to-video`	圖生影片
`grok-imagine-text-to-video`	文生影片
`grok-imagine-upscale`	影片轉影片

Other

Model	公開操作
`topaz-video-upscale`	影片轉影片

核心

文字

檔案與批次

圖像與媒體

非同步任務

Gemini 原生

管理

概覽

請求主體

相容說明

輸入最佳實踐

回應

圖生影片

參考圖生影片

首尾幀控制

影片轉影片

動作控制

Audio-to-Video 與 Video Extension 的目前可用性

目前啟用的公開影片模型

OpenAI

Kuaishou

Google

ByteDance

MiniMax

Alibaba

Shengshu

xAI

Other

核心

文字

檔案與批次

圖像與媒體

非同步任務

Gemini 原生

管理

​概覽

​請求主體

​相容說明

​輸入最佳實踐

​回應

​圖生影片

​參考圖生影片

​首尾幀控制

​影片轉影片

​動作控制

​Audio-to-Video 與 Video Extension 的目前可用性

​目前啟用的公開影片模型

​OpenAI

​Kuaishou

​Google

​ByteDance

​MiniMax

​Alibaba

​Shengshu

​xAI

​Other

概覽

請求主體

相容說明

輸入最佳實踐

回應

圖生影片

參考圖生影片

首尾幀控制

影片轉影片

動作控制

Audio-to-Video 與 Video Extension 的目前可用性

目前啟用的公開影片模型

OpenAI

Kuaishou

Google

ByteDance

MiniMax

Alibaba

Shengshu

xAI

Other