API Docs
Updates
- 2025/11/28 Added resolution parameter support for 768 and 1024.
Image-to-Video
Documentation Overview
This RESTful API enables users to generate video content from a prompt and reference image. The service supports asynchronous video generation tasks and provides endpoints to query status and download outputs.
Authentication
All API requests must include a Bearer Token in the headers. Log in to the LightJump - AI Video Creation Platform to obtain your API key.
Authorization: Bearer YOUR_API_TOKENAPI Details
Create Video Task
Endpoint: POST /api/v1/video/generate
Purpose: Submit an image and prompt to create a video generation task.
Headers
- Authorization: Bearer YOUR_API_TOKEN
- Content-Type: application/json
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | - | Text describing the video. More detail leads to better results. |
| image | string | Yes | - | Reference image URL used to guide the generation. |
| resolution | string | No | "768" | Optional resolution: "540", "720", "768", "1024" |
Request Example
curl 'https://api.lightjump.online/api/v1/video/generate' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "A dynamic 3D animation describing Mario dancing in the Mushroom Kingdom. As the background changes, he spins, flips, and bursts into energetic moves.",
"image": "https://example.com/images/reference.jpg"
}'Response Example
Success
{
"success": true,
"task_id": "ab851f16-193f-4d5d-98ea-79bfcb76e1af",
"status": "queued",
"message": "Task queued. Position: 1"
}Failure
{
"success": false,
"message": "Failed to create task: invalid parameters"
}Query Task Status
Endpoint: GET /api/v1/video/tasks/{taskId}
Purpose: Query the progress and status of a video generation task by ID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| taskId | string | Task ID returned when the task was created. |
Request Example
curl 'https://api.lightjump.online/api/v1/video/tasks/ab851f16-193f-4d5d-98ea-79bfcb76e1af' \
-H 'Authorization: Bearer xxxx'Response Example
Queued/Processing
{
"success": true,
"task_id": "task_123456789",
"status": "queued",
"progress": 0,
"message": "Waiting in queue",
"created_at": "2024-01-15 10:30:45",
"queue_info": {
"queue_position": 3,
"estimated_wait_time": "30s",
"is_processing": true,
"queue_size": 5
}
}Completed
{
"success": true,
"task_id": "task_123456789",
"status": "completed",
"progress": 100,
"message": "Video generated",
"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"
}Failed
{
"success": true,
"task_id": "task_123456789",
"status": "failed",
"progress": 0,
"message": "Generation failed",
"created_at": "2024-01-15 10:30:45",
"error_message": "Error during generation"
}Code Samples
Python Sample
import time
import requests
# API configuration
API_BASE_URL = "https://api.lightjump.online/api/v1/video"
API_TOKEN = "YOUR_API_TOKEN" # Replace with your API token
# Submit a video generation task
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
}
# Send POST request to create the task
response = requests.post(url, json=data, headers=headers)
# If successful, return task ID
if response.status_code == 200:
result = response.json()
if result["success"]:
print(f"Task created, ID: {result['task_id']}")
return result['task_id']
else:
print(f"Create failed: {result.get('message', 'Unknown error')}")
return None
else:
print(f"Request failed: {response.status_code}")
return None
# Query task status
def check_task_status(task_id):
url = f"{API_BASE_URL}/tasks/{task_id}"
headers = {
"Authorization": f"Bearer {API_TOKEN}"
}
# Send GET request
response = requests.get(url, headers=headers)
# If successful, return status
if response.status_code == 200:
result = response.json()
if result["success"]:
return result
else:
print(f"Query failed: {result.get('message', 'Unknown error')}")
return None
else:
print(f"Request failed: {response.status_code}")
return None
# Download the generated video
def download_video(video_url, task_id):
response = requests.get(video_url)
# If successful, save the file
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"Download complete: {file_name}")
else:
print(f"Download failed: {response.status_code}")
# Main flow
def generate_video_and_download(prompt, image_url):
# 1. Create task
task_id = create_video_task(prompt, image_url)
if not task_id:
return
# 2. Poll status until completion
while True:
print(f"Checking task status, 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"Generation failed: {task_status.get('error_message', 'Unknown error')}")
break
else:
print(f"Status: {status}. Waiting... (Progress: {task_status['progress']}%)")
time.sleep(30)
else:
print("Query failed, retrying...")
time.sleep(30)
# Sample input
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" # Reference image URL
# Run
generate_video_and_download(prompt, image_url)
Java Sample
import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.TimeUnit;
import org.json.JSONObject;
public class VideoGenerationClient {
// API configuration
private static final String API_BASE_URL = "https://api.lightjump.online/api/v1/video";
private static final String API_TOKEN = "YOUR_API_TOKEN"; // Replace with your API Token
// Submit a video generation task
public static String createVideoTask(String prompt, String imageUrl) {
try {
// Request URL
String urlString = API_BASE_URL + "/generate";
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Request method and headers
connection.setRequestMethod("POST");
connection.setRequestProperty("Authorization", "Bearer " + API_TOKEN);
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
// Create request payload
JSONObject requestData = new JSONObject();
requestData.put("prompt", prompt);
requestData.put("image", imageUrl);
// Send request payload
try (OutputStream os = connection.getOutputStream()) {
byte[] input = requestData.toString().getBytes(StandardCharsets.UTF_8);
os.write(input, 0, input.length);
}
// Read response
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);
}
// Parse JSON response
JSONObject responseJson = new JSONObject(response.toString());
if (responseJson.getBoolean("success")) {
String taskId = responseJson.getString("task_id");
System.out.println("Task created, ID: " + taskId);
return taskId;
} else {
System.out.println("Create failed: " + responseJson.optString("message", "Unknown error"));
}
}
} else {
System.out.println("Request failed, HTTP code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
// Query task status
public static JSONObject checkTaskStatus(String taskId) {
try {
// Request URL
String urlString = API_BASE_URL + "/tasks/" + taskId;
URL url = new URL(urlString);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Request headers
connection.setRequestMethod("GET");
connection.setRequestProperty("Authorization", "Bearer " + API_TOKEN);
// Read response
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);
}
// Parse JSON response
JSONObject responseJson = new JSONObject(response.toString());
if (responseJson.getBoolean("success")) {
return responseJson;
} else {
System.out.println("Query failed: " + responseJson.optString("message", "Unknown error"));
}
}
} else {
System.out.println("Request failed, HTTP code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
// Download generated video
public static void downloadVideo(String videoUrl, String taskId) {
try {
URL url = new URL(videoUrl);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
// Read response
int responseCode = connection.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
try (InputStream inputStream = connection.getInputStream()) {
// Save file path
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("Download complete: " + fileName);
}
}
} else {
System.out.println("Download failed, HTTP code: " + responseCode);
}
} catch (Exception e) {
e.printStackTrace();
}
}
// Main flow
public static void generateVideoAndDownload(String prompt, String imageUrl) {
// 1. Create task
String taskId = createVideoTask(prompt, imageUrl);
if (taskId == null) {
return;
}
// 2. Poll status until completion
while (true) {
System.out.println("Checking task status, ID: " + taskId + "...");
JSONObject taskStatus = checkTaskStatus(taskId);
if (taskStatus != null) {
String status = taskStatus.getString("status");
if ("completed".equals(status)) {
// Task completed, download video
String videoUrl = taskStatus.getString("video_url");
downloadVideo(videoUrl, taskId);
break;
} else if ("failed".equals(status)) {
System.out.println("Generation failed: " + taskStatus.optString("error_message", "Unknown error"));
break;
} else {
// Queued or processing, wait 30 seconds
System.out.println("Status: " + status + ". Waiting... (Progress: " + taskStatus.getInt("progress") + "%)");
try {
TimeUnit.SECONDS.sleep(30);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
} else {
System.out.println("Query failed, retrying...");
try {
TimeUnit.SECONDS.sleep(30);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
}
public static void main(String[] args) {
// Sample input
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"; // Reference image URL
// Run
generateVideoAndDownload(prompt, imageUrl);
}
}
Go Sample
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"io/ioutil"
"net/http"
"time"
)
// API configuration
const (
apiBaseURL = "https://api.lightjump.online/api/v1/video"
apiToken = "YOUR_API_TOKEN" // Replace with your API token
)
// Request payload for creating a task
type CreateTaskRequest struct {
Prompt string `json:"prompt"`
Image string `json:"image"`
}
// Response payload for task status
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"`
}
// Create a video generation task
func createVideoTask(prompt, imageURL string) (string, error) {
url := fmt.Sprintf("%s/generate", apiBaseURL)
requestData := CreateTaskRequest{
Prompt: prompt,
Image: imageURL,
}
jsonData, err := json.Marshal(requestData)
if err != nil {
return "", fmt.Errorf("Failed to encode request: %v", err)
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
return "", fmt.Errorf("Failed to create request: %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("Request failed: %v", err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return "", fmt.Errorf("Failed to read response: %v", err)
}
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil {
return "", fmt.Errorf("Failed to parse response: %v", err)
}
if success, ok := result["success"].(bool); ok && success {
if taskID, ok := result["task_id"].(string); ok {
fmt.Printf("Task created, ID: %s\n", taskID)
return taskID, nil
}
}
return "", fmt.Errorf("Create failed: %s", result["message"])
}
// Query task status
func checkTaskStatus(taskID string) (*TaskStatusResponse, error) {
url := fmt.Sprintf("%s/tasks/%s", apiBaseURL, taskID)
req, err := http.NewRequest("GET", url, nil)
if err != nil {
return nil, fmt.Errorf("Failed to create request: %v", err)
}
req.Header.Set("Authorization", "Bearer "+apiToken)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, fmt.Errorf("Request failed: %v", err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, fmt.Errorf("Failed to read response: %v", err)
}
var statusResponse TaskStatusResponse
if err := json.Unmarshal(body, &statusResponse); err != nil {
return nil, fmt.Errorf("Failed to parse response: %v", err)
}
if statusResponse.Success {
return &statusResponse, nil
}
return nil, fmt.Errorf("Query failed: %s", statusResponse.Message)
}
// Download video
func downloadVideo(videoURL, taskID string) error {
resp, err := http.Get(videoURL)
if err != nil {
return fmt.Errorf("Download failed: %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("Failed to create file: %v", err)
}
defer outFile.Close()
_, err = io.Copy(outFile, resp.Body)
if err != nil {
return fmt.Errorf("Failed to write file: %v", err)
}
fmt.Printf("Download complete: %s\n", fileName)
return nil
}
// Main flow
func generateVideoAndDownload(prompt, imageURL string) {
// 1. Create task
taskID, err := createVideoTask(prompt, imageURL)
if err != nil {
fmt.Println("Create failed:", err)
return
}
// 2. Poll status until completion
for {
fmt.Printf("Checking task status, ID: %s...\n", taskID)
statusResponse, err := checkTaskStatus(taskID)
if err != nil {
fmt.Println("Query failed:", err)
return
}
switch statusResponse.Status {
case "completed":
err := downloadVideo(statusResponse.VideoURL, taskID)
if err != nil {
fmt.Println("Download failed:", err)
}
return
case "failed":
fmt.Println("Generation failed:", statusResponse.ErrorMessage)
return
default:
fmt.Printf("Status: %s. Progress: %d%%\n", statusResponse.Status, statusResponse.Progress)
time.Sleep(30 * time.Second)
}
}
}
func main() {
// Sample input
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" // Reference image URL
// Run
generateVideoAndDownload(prompt, imageURL)
}
Notes
- 1. Image format: provide a valid URL and ensure the image is accessible.
- 2. Video generation is asynchronous: poll task status until completion.
- 3. Video URL validity: generated links expire after 30 days; download promptly.
- 4. API Token: each user has an API Token for authentication—store it securely.
FAQ
How do I know when a task is complete?
Poll GET /api/v1/video/tasks/{taskId}. When status is completed, the task is done.
What if the task fails?
If status is failed, an error_message is returned. Adjust parameters and retry.