接口文档
更新公告
- 2025/11/28 新增分辨率参数支持 768,1024。
图生视频
文档概述
本接口文档描述了“图生视频”服务的 RESTful API,允许用户通过提供文本提示词和参考图像生成视频内容。该服务支持异步视频生成任务,并提供多种接口查询任务状态、下载生成视频等功能。
认证方式
所有 API 请求都需要在请求头中携带 Bearer Token 认证,请在浮光AI - AI视频创作平台页面登录后获取你的 API密钥。
Authorization: Bearer YOUR_API_TOKEN接口详情
创建视频生成任务
接口: POST /api/v1/video/generate
功能: 提交图像和文本提示词,创建视频生成任务。
请求头
- Authorization: Bearer YOUR_API_TOKEN
- Content-Type: application/json
请求参数
| 参数 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| prompt | string | 是 | - | 描述视频内容的文本。可以详细描述场景、角色、动作、光照等,越详细生成的效果越准确 |
| image | string | 是 | - | 参考图像,可以是一个图片的 URL,用来帮助生成视频。 |
| resolution | string | 否 | "768" | 分辨率,可选参数"540","720","768","1024" |
请求示例
curl 'https://api.lightjump.online/api/v1/video/generate' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "一个动态的 3D 动画,描述 Mario 在蘑菇王国中跳舞的场景。随着背景的变化,他旋转、翻滚、爆发出活力十足的动作。",
"image": "https://example.com/images/reference.jpg"
}'响应示例
请求成功
{
"success": true,
"task_id": "ab851f16-193f-4d5d-98ea-79bfcb76e1af",
"status": "queued",
"message": "任务已加入队列,当前队列位置: 1"
}请求失败
{
"success": false,
"message": "创建任务失败: 参数错误"
}查询任务状态
接口: GET /api/v1/video/tasks/{taskId}
功能: 根据任务 ID 查询视频生成的进度和状态。
路径参数
| 参数 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务的唯一标识符,从创建任务时返回。 |
请求示例
curl 'https://api.lightjump.online/api/v1/video/tasks/ab851f16-193f-4d5d-98ea-79bfcb76e1af' \
-H 'Authorization: Bearer xxxx'响应示例
任务排队中/处理中
{
"success": true,
"task_id": "task_123456789",
"status": "queued",
"progress": 0,
"message": "正在排队等待处理",
"created_at": "2024-01-15 10:30:45",
"queue_info": {
"queue_position": 3,
"estimated_wait_time": "30秒",
"is_processing": true,
"queue_size": 5
}
}任务生成完成
{
"success": true,
"task_id": "task_123456789",
"status": "completed",
"progress": 100,
"message": "视频生成完成",
"created_at": "2024-01-15 10:30:45",
"updated_at": "2024-01-15 10:35:20",
"video_url": "https://example.com/videos/task_123456789.mp4"
}任务生成失败
{
"success": true,
"task_id": "task_123456789",
"status": "failed",
"progress": 0,
"message": "视频生成失败",
"created_at": "2024-01-15 10:30:45",
"error_message": "生成过程中发生错误"
}代码示例
Python代码示例
import time
import requests
# API 配置
API_BASE_URL = "https://api.lightjump.online/api/v1/video"
API_TOKEN = "YOUR_API_TOKEN" # 请替换为你自己的 API Token
# 提交视频生成任务的函数
def create_video_task(prompt, image_url):
url = f"{API_BASE_URL}/generate"
headers = {
"Authorization": f"Bearer {API_TOKEN}",
"Content-Type": "application/json"
}
data = {
"prompt": prompt,
"image": image_url
}
# 发送 POST 请求创建任务
response = requests.post(url, json=data, headers=headers)
# 如果请求成功,返回任务 ID,否则返回 None
if response.status_code == 200:
result = response.json()
if result["success"]:
print(f"任务已创建,任务 ID: {result['task_id']}")
return result['task_id']
else:
print(f"创建任务失败: {result.get('message', '未知错误')}")
return None
else:
print(f"请求失败: {response.status_code}")
return None
# 查询任务状态的函数
def check_task_status(task_id):
url = f"{API_BASE_URL}/tasks/{task_id}"
headers = {
"Authorization": f"Bearer {API_TOKEN}"
}
# 发送 GET 请求查询任务状态
response = requests.get(url, headers=headers)
# 如果请求成功,返回任务状态,否则返回 None
if response.status_code == 200:
result = response.json()
if result["success"]:
return result
else:
print(f"查询任务失败: {result.get('message', '未知错误')}")
return None
else:
print(f"请求失败: {response.status_code}")
return None
# 下载生成的视频文件
def download_video(video_url, task_id):
# 发送 GET 请求下载视频
response = requests.get(video_url)
# 如果请求成功,保存视频文件
if response.status_code == 200:
file_name = f"generated_video_{task_id}.mp4"
with open(file_name, 'wb') as video_file:
video_file.write(response.content)
print(f"视频下载完成: {file_name}")
else:
print(f"下载视频失败: {response.status_code}")
# 主函数,执行整个视频生成任务
def generate_video_and_download(prompt, image_url):
# 1. 创建视频生成任务
task_id = create_video_task(prompt, image_url)
if not task_id:
return
# 2. 轮询查询任务状态,直到任务完成
while True:
print(f"正在检查任务状态,任务 ID: {task_id}...")
task_status = check_task_status(task_id)
if task_status:
status = task_status["status"]
if status == "completed":
# 任务完成,下载视频
video_url = task_status["video_url"]
download_video(video_url, task_id)
break
elif status == "failed":
print(f"任务生成失败: {task_status.get('error_message', '未知错误')}")
break
else:
# 任务仍在排队或处理中,等待 30 秒后重试
print(f"任务状态: {status}. 正在等待...(进度: {task_status['progress']}%)")
time.sleep(30)
else:
print("查询任务状态失败,稍后重试...")
time.sleep(30)
# 示例输入
prompt = "A dynamic 3D animation of Mario performing an energetic breakdance routine in a vibrant Mushroom Kingdom setting. He spins on his back, pops and locks with precise movements, then finishes with a stylish flip. The character maintains perfect likeness while moving fluidly with exaggerated cartoon physics. Soft volumetric lighting, cinematic camera movement circling around the character, high detail textures on his overalls and cap. Trending on ArtStation, Unreal Engine 5 render, octane render, 4K resolution"
image_url = "https://example.com/images/reference.jpg" # 参考图像的 URL
# 调用主函数
generate_video_and_download(prompt, image_url)
Java代码示例
import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.TimeUnit;
import org.json.JSONObject;
public class VideoGenerationClient {
// API 配置
private static final String API_BASE_URL = "https://api.lightjump.online/api/v1/video";
private static final String API_TOKEN = "YOUR_API_TOKEN"; // 请替换为你自己的 API Token
// 提交视频生成任务
public static String createVideoTask(String prompt, String imageUrl) {
try {
// 请求的 URL
String urlString = API_BASE_URL + "/generate";
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// 设置请求方式和头部信息
connection.setRequestMethod("POST");
connection.setRequestProperty("Authorization", "Bearer " + API_TOKEN);
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
// 创建请求数据
JSONObject requestData = new JSONObject();
requestData.put("prompt", prompt);
requestData.put("image", imageUrl);
// 发送请求数据
try (OutputStream os = connection.getOutputStream()) {
byte[] input = requestData.toString().getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
}
// 获取响应
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
// 读取响应
try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
StringBuilder response = new StringBuilder();
String inputLine;
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
// 解析 JSON 响应
JSONObject responseJson = new JSONObject(response.toString());
if (responseJson.getBoolean("success")) {
String taskId = responseJson.getString("task_id");
System.out.println("任务已创建,任务 ID: " + taskId);
return taskId;
} else {
System.out.println("创建任务失败: " + responseJson.optString("message", "未知错误"));
}
}
} else {
System.out.println("请求失败,HTTP 错误代码: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
// 查询任务状态
public static JSONObject checkTaskStatus(String taskId) {
try {
// 请求的 URL
String urlString = API_BASE_URL + "/tasks/" + taskId;
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// 设置请求头部
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", "Bearer " + API_TOKEN);
// 获取响应
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
// 读取响应
try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
StringBuilder response = new StringBuilder();
String inputLine;
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
// 解析 JSON 响应
JSONObject responseJson = new JSONObject(response.toString());
if (responseJson.getBoolean("success")) {
return responseJson;
} else {
System.out.println("查询任务状态失败: " + responseJson.optString("message", "未知错误"));
}
}
} else {
System.out.println("请求失败,HTTP 错误代码: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
// 下载生成的视频
public static void downloadVideo(String videoUrl, String taskId) {
try {
URL url = new URL(videoUrl);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// 获取响应
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
// 获取视频输入流
try (InputStream inputStream = connection.getInputStream()) {
// 设置保存文件路径
String fileName = "generated_video_" + taskId + ".mp4";
try (FileOutputStream outputStream = new FileOutputStream(fileName)) {
byte[] buffer = new byte[4096];
int bytesRead;
while ((bytesRead = inputStream.read(buffer)) != -1) {
outputStream.write(buffer, 0, bytesRead);
}
System.out.println("视频下载完成: " + fileName);
}
}
} else {
System.out.println("下载视频失败,HTTP 错误代码: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
// 主函数,执行整个视频生成任务
public static void generateVideoAndDownload(String prompt, String imageUrl) {
// 1. 创建视频生成任务
String taskId = createVideoTask(prompt, imageUrl);
if (taskId == null) {
return;
}
// 2. 轮询查询任务状态,直到任务完成
while (true) {
System.out.println("正在检查任务状态,任务 ID: " + taskId + "...");
JSONObject taskStatus = checkTaskStatus(taskId);
if (taskStatus != null) {
String status = taskStatus.getString("status");
if ("completed".equals(status)) {
// 任务完成,下载视频
String videoUrl = taskStatus.getString("video_url");
downloadVideo(videoUrl, taskId);
break;
} else if ("failed".equals(status)) {
System.out.println("任务生成失败: " + taskStatus.optString("error_message", "未知错误"));
break;
} else {
// 任务仍在排队或处理中,等待 30 秒后重试
System.out.println("任务状态: " + status + ". 正在等待...(进度: " + taskStatus.getInt("progress") + "%)");
try {
TimeUnit.SECONDS.sleep(30);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
} else {
System.out.println("查询任务状态失败,稍后重试...");
try {
TimeUnit.SECONDS.sleep(30);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
}
public static void main(String[] args) {
// 示例输入
String prompt = "A dynamic 3D animation of Mario performing an energetic breakdance routine in a vibrant Mushroom Kingdom setting. He spins on his back, pops and locks with precise movements, then finishes with a stylish flip. The character maintains perfect likeness while moving fluidly with exaggerated cartoon physics. Soft volumetric lighting, cinematic camera movement circling around the character, high detail textures on his overalls and cap. Trending on ArtStation, Unreal Engine 5 render, octane render, 4K resolution";
String imageUrl = "https://example.com/images/reference.jpg"; // 参考图像的 URL
// 调用主函数
generateVideoAndDownload(prompt, imageUrl);
}
}
Go代码示例
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"io/ioutil"
"net/http"
"time"
)
// API 配置
const (
apiBaseURL = "https://api.lightjump.online/api/v1/video"
apiToken = "YOUR_API_TOKEN" // 请替换为你自己的 API Token
)
// 创建视频生成任务的请求结构体
type CreateTaskRequest struct {
Prompt string `json:"prompt"`
Image string `json:"image"`
}
// 查询任务状态的响应结构体
type TaskStatusResponse struct {
Success bool `json:"success"`
TaskID string `json:"task_id"`
Status string `json:"status"`
Progress int `json:"progress"`
Message string `json:"message"`
VideoURL string `json:"video_url,omitempty"`
ErrorMessage string `json:"error_message,omitempty"`
QueueInfo struct {
QueuePosition int `json:"queue_position"`
EstimatedWaitTime string `json:"estimated_wait_time"`
IsProcessing bool `json:"is_processing"`
QueueSize int `json:"queue_size"`
} `json:"queue_info,omitempty"`
}
// 创建视频生成任务
func createVideoTask(prompt, imageURL string) (string, error) {
url := fmt.Sprintf("%s/generate", apiBaseURL)
// 创建请求体
requestData := CreateTaskRequest{
Prompt: prompt,
Image: imageURL,
}
// 将请求数据编码为 JSON
jsonData, err := json.Marshal(requestData)
if err != nil {
return "", fmt.Errorf("无法编码请求数据: %v", err)
}
// 发送 POST 请求
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
return "", fmt.Errorf("创建请求失败: %v", err)
}
// 设置请求头
req.Header.Set("Authorization", "Bearer "+apiToken)
req.Header.Set("Content-Type", "application/json")
// 发送请求
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return "", fmt.Errorf("请求失败: %v", err)
}
defer resp.Body.Close()
// 读取响应
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return "", fmt.Errorf("读取响应失败: %v", err)
}
// 解析响应
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil {
return "", fmt.Errorf("解析响应失败: %v", err)
}
// 检查请求是否成功
if success, ok := result["success"].(bool); ok && success {
if taskID, ok := result["task_id"].(string); ok {
fmt.Printf("任务已创建,任务 ID: %s\n", taskID)
return taskID, nil
}
}
return "", fmt.Errorf("创建任务失败: %s", result["message"])
}
// 查询任务状态
func checkTaskStatus(taskID string) (*TaskStatusResponse, error) {
url := fmt.Sprintf("%s/tasks/%s", apiBaseURL, taskID)
// 创建 GET 请求
req, err := http.NewRequest("GET", url, nil)
if err != nil {
return nil, fmt.Errorf("创建请求失败: %v", err)
}
// 设置请求头
req.Header.Set("Authorization", "Bearer "+apiToken)
// 发送请求
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, fmt.Errorf("请求失败: %v", err)
}
defer resp.Body.Close()
// 读取响应
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, fmt.Errorf("读取响应失败: %v", err)
}
// 解析响应
var statusResponse TaskStatusResponse
if err := json.Unmarshal(body, &statusResponse); err != nil {
return nil, fmt.Errorf("解析响应失败: %v", err)
}
// 如果请求成功,返回任务状态
if statusResponse.Success {
return &statusResponse, nil
}
return nil, fmt.Errorf("查询任务状态失败: %s", statusResponse.Message)
}
// 下载视频
func downloadVideo(videoURL, taskID string) error {
// 发送 GET 请求下载视频
resp, err := http.Get(videoURL)
if err != nil {
return fmt.Errorf("下载视频失败: %v", err)
}
defer resp.Body.Close()
// 创建文件保存视频
fileName := fmt.Sprintf("generated_video_%s.mp4", taskID)
outFile, err := os.Create(fileName)
if err != nil {
return fmt.Errorf("创建文件失败: %v", err)
}
defer outFile.Close()
// 将视频内容写入文件
_, err = io.Copy(outFile, resp.Body)
if err != nil {
return fmt.Errorf("写入文件失败: %v", err)
}
fmt.Printf("视频下载完成: %s\n", fileName)
return nil
}
// 主函数,执行整个视频生成任务
func generateVideoAndDownload(prompt, imageURL string) {
// 1. 创建视频生成任务
taskID, err := createVideoTask(prompt, imageURL)
if err != nil {
fmt.Println("创建任务失败:", err)
return
}
// 2. 轮询查询任务状态,直到任务完成
for {
fmt.Printf("正在检查任务状态,任务 ID: %s...\n", taskID)
statusResponse, err := checkTaskStatus(taskID)
if err != nil {
fmt.Println("查询任务状态失败:", err)
return
}
switch statusResponse.Status {
case "completed":
// 任务完成,下载视频
err := downloadVideo(statusResponse.VideoURL, taskID)
if err != nil {
fmt.Println("下载视频失败:", err)
}
return
case "failed":
// 任务失败
fmt.Println("任务生成失败:", statusResponse.ErrorMessage)
return
default:
// 任务排队或处理中,等待一段时间再轮询
fmt.Printf("任务状态: %s. 进度: %d%%\n", statusResponse.Status, statusResponse.Progress)
time.Sleep(30 * time.Second)
}
}
}
func main() {
// 示例输入
prompt := "A dynamic 3D animation of Mario performing an energetic breakdance routine in a vibrant Mushroom Kingdom setting. He spins on his back, pops and locks with precise movements, then finishes with a stylish flip. The character maintains perfect likeness while moving fluidly with exaggerated cartoon physics. Soft volumetric lighting, cinematic camera movement circling around the character, high detail textures on his overalls and cap. Trending on ArtStation, Unreal Engine 5 render, octane render, 4K resolution"
imageURL := "https://example.com/images/reference.jpg" // 参考图像的 URL
// 调用主函数
generateVideoAndDownload(prompt, imageURL)
}
注意事项
- 1. 图像格式:图像可以是有效的 URL ,请确保图片可被正确下载。
- 2. 视频生成是异步处理:视频生成是后台任务,建议定期轮询任务状态,直到任务完成。
- 3. 视频链接时效性:生成的视频链接有效期为 30 天,过期后无法下载,记得及时下载。
- 4. API Token:每个用户都有一个 API Token,用于验证身份,请确保将其安全存储,不要公开分享。
常见问题
如何查询任务是否完成?
只需定期调用 GET /api/v1/video/tasks/{taskId} 接口查询任务状态。当返回的 status 为 completed 时,表示任务已完成。
任务失败怎么办?
如果任务失败,status 会为 failed,并且会返回详细的 error_message。根据错误信息调整任务参数后,可以重新提交任务。