Veo Video Generation
Call Veo models through the unified video task interface; describes available models, request fields, and query methods in the current project.
- Submission route:
POST /v1/videos - Task query:
GET /v1/videos/{task_id} - Content download:
GET /v1/videos/{task_id}/content
Legacy compatibility routes POST /v1/video/generations and GET /v1/video/generations/{task_id} still exist; new integrations should use /v1/videos, matching the playground and model endpoint metadata.
Submission Request Example
cURL
curl --request POST \
--url https://api.magickapi.com/v1/videos \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "veo-3.1-fast-generate-preview",
"prompt": "海豚在碧蓝海洋中跳跃",
"duration": 8,
"size": "1280x720",
"images": [
"https://example.com/first-frame.png"
],
"metadata": {
"generateAudio": true,
"seed": 7
}
}'Successful Submission Response Example
The submission route returns an OpenAI-style video object corresponding to the public task_id:
{
"id": "task_01KXYZ1234567890ABCDE",
"task_id": "task_01KXYZ1234567890ABCDE",
"object": "video",
"model": "veo-3.1-fast-generate-preview",
"status": "queued",
"progress": 0,
"created_at": 1712345678
}Query and Download
cURL Query Task Status
curl https://api.magickapi.com/v1/videos/task_01KXYZ1234567890ABCDE \
-H 'Authorization: Bearer YOUR_API_KEY'cURL Download Video File
curl -L https://api.magickapi.com/v1/videos/task_01KXYZ1234567890ABCDE/content \
-H 'Authorization: Bearer YOUR_API_KEY' \
--output veo-output.mp4Python Polling and Download
import time
import requests
base_url = "https://api.magickapi.com"
api_key = "YOUR_API_KEY"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
submit_payload = {
"model": "veo-3.1-fast-generate-preview",
"prompt": "海豚在碧蓝海洋中跳跃",
"duration": 8,
"size": "1280x720",
"images": [
"https://example.com/first-frame.png"
],
"metadata": {
"generateAudio": True,
"seed": 7,
},
}
submit_resp = requests.post(
f"{base_url}/v1/videos",
headers=headers,
json=submit_payload,
timeout=300,
)
submit_resp.raise_for_status()
task = submit_resp.json()
task_id = task.get("id") or task.get("task_id")
print("task_id:", task_id)
while True:
query_resp = requests.get(
f"{base_url}/v1/videos/{task_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=300,
)
query_resp.raise_for_status()
status = query_resp.json()
print(status)
if status["status"] == "completed":
download_resp = requests.get(
f"{base_url}/v1/videos/{task_id}/content",
headers={"Authorization": f"Bearer {api_key}"},
timeout=600,
)
download_resp.raise_for_status()
with open("veo-output.mp4", "wb") as f:
f.write(download_resp.content)
print("saved: veo-output.mp4")
break
if status["status"] == "failed":
message = (status.get("error") or {}).get("message", "video generation failed")
raise RuntimeError(message)
time.sleep(10)Node.js Polling and Download
import { writeFile } from "node:fs/promises";
const baseUrl = "https://api.magickapi.com";
const apiKey = "YOUR_API_KEY";
const submitPayload = {
model: "veo-3.1-fast-generate-preview",
prompt: "海豚在碧蓝海洋中跳跃",
duration: 8,
size: "1280x720",
images: ["https://example.com/first-frame.png"],
metadata: {
generateAudio: true,
seed: 7,
},
};
const submitResp = await fetch(`${baseUrl}/v1/videos`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify(submitPayload),
});
if (!submitResp.ok) {
throw new Error(await submitResp.text());
}
const task = await submitResp.json();
const taskId = task.id || task.task_id;
console.log("task_id:", taskId);
while (true) {
const queryResp = await fetch(`${baseUrl}/v1/videos/${taskId}`, {
headers: {
Authorization: `Bearer ${apiKey}`,
},
});
if (!queryResp.ok) {
throw new Error(await queryResp.text());
}
const status = await queryResp.json();
console.log(status);
if (status.status === "completed") {
const downloadResp = await fetch(`${baseUrl}/v1/videos/${taskId}/content`, {
headers: {
Authorization: `Bearer ${apiKey}`,
},
});
if (!downloadResp.ok) {
throw new Error(await downloadResp.text());
}
const buffer = Buffer.from(await downloadResp.arrayBuffer());
await writeFile("veo-output.mp4", buffer);
console.log("saved: veo-output.mp4");
break;
}
if (status.status === "failed") {
throw new Error(status.error?.message || "video generation failed");
}
await new Promise((resolve) => setTimeout(resolve, 10000));
}Public Top-Level Fields Actually Parsed by the Current Project
modelpromptmodeimageimagesinput_referencesizedurationsecondsmetadata
Veo-Related Parameter Writing
size
For Veo, it is recommended to directly pass pixel dimensions, for example:
1280x720720x12803840x2160
The project will automatically derive default resolution and aspectRatio based on size.
metadata
Veo extended parameters should be placed in metadata, for example:
aspectRatioresolutionnegativePromptseedgenerateAudio
Legacy Compatibility Query
The legacy task query route is still available:
curl https://api.magickapi.com/v1/video/generations/task_01KXYZ1234567890ABCDE \
-H 'Authorization: Bearer YOUR_API_KEY'Last updated on
Gemini 3.1 Flash Image
Describes how `gemini-3.1-flash-image-preview` is integrated in the current project: it belongs to the Gemini native model and does not use the unified image interface.
Wan 2.7 Video Generation
Call Wan 2.7 text-to-video, image-to-video, reference-to-video, and video editing models through the unified video task API.