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_TOKEN

API 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
ParameterTypeRequiredDefaultDescription
promptstringYes-Text describing the video. More detail leads to better results.
imagestringYes-Reference image URL used to guide the generation.
resolutionstringNo"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
ParameterTypeDescription
taskIdstringTask 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. 1. Image format: provide a valid URL and ensure the image is accessible.
  2. 2. Video generation is asynchronous: poll task status until completion.
  3. 3. Video URL validity: generated links expire after 30 days; download promptly.
  4. 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.