Image to Video API Documentation

Base URL: https://api.ideal.house
Version: v1
Updated: 2026-03-25

---

📖 Overview

The Image to Video API allows you to generate AI-driven videos from a single source image, or by specifying both a first frame and a last frame image to control the beginning and end of the generated video. The workflow is asynchronous and involves two steps:

1. Create a task — Submit your image(s), model type, duration, and resolution, then receive a taskId.
2. Poll for results — Use the taskId to query task status and retrieve the generated video.

---

🔐 Authentication

All API requests must be authenticated using an API Key.

Include your API Key in the request header:

Header	Value
APIKEY	your_api_key_here

⚠️ Keep your API Key secure. Do not expose it in client-side code or public repositories.

---

💰 Credits Deduction

[!WARNING] 🪙 Credits are deducted based on the selected modelType, resolution, duration, and whether generateAudio is enabled upon successful task creation. If the task ultimately fails, the deducted credits will be automatically refunded to your account.
Insufficient credits will return error code 9051. 📄 See Credits Deduction Reference.

Flash model (modelType: "Flash", default):

Resolution	Duration	Credits Deducted
480p	5s	10 credits
480p	10s	20 credits
720p	5s	20 credits
720p	10s	40 credits
1080p	5s	40 credits
1080p	10s	80 credits

Base model (modelType: "Base", generateAudio: false):

Resolution	Duration	Credits Deducted
480p	5s	8 credits
480p	10s	16 credits
720p	5s	16 credits
720p	10s	32 credits
1080p	5s	32 credits
1080p	10s	64 credits

Base model with audio (modelType: "Base", generateAudio: true):

Resolution	Duration	Credits Deducted
480p	5s	16 credits
480p	10s	32 credits
720p	5s	32 credits
720p	10s	64 credits
1080p	5s	64 credits
1080p	10s	128 credits

---

📌 API Endpoints

---

1. Create Image to Video Task

Creates a new AI image-to-video generation task and returns a unique taskId for polling.

Endpoint

POST /api/v1/imageToVideo/generate

Request Headers

Header	Required	Description
APIKEY	✅ Yes	Your API authentication key
Content-Type	✅ Yes	application/json

Request Body

Field	Type	Required	Description
imageUrl	string	✅ Yes	URL of the source image. In first-last frame mode, this serves as the first frame
duration	integer	✅ Yes	Video duration in seconds. Enum: 5, 10
resolution	string	✅ Yes	Video output resolution. Enum: 480p, 720p, 1080p
modelType	string	❌ Optional	Model type to use for generation. Enum: Flash, Base. Defaults to Flash
generateAudio	boolean	❌ Optional	Whether to generate background audio for the video. Only applicable when modelType is Base. Defaults to false
prompt	string	❌ Optional	Text prompt to guide the video generation style and motion
lastImageUrl	string	❌ Optional	URL of the last frame image. When provided, enables first-last frame mode: the video will transition from imageUrl (first frame) to lastImageUrl (last frame)

💡 First-Last Frame Mode: If lastImageUrl is provided, the API generates a video that smoothly transitions from the first frame image (imageUrl) to the last frame image (lastImageUrl), giving you precise control over the start and end of the video.

---

Model Types

Value	Description
Flash	Default. Faster generation speed with high quality output
Base	Alternative model — supports optional AI audio generation (generateAudio)

---

Duration Options

Value	Description
5	5-second video
10	10-second video

---

Resolution Options

Value	Description
480p	Standard definition — faster processing
720p	High definition — higher quality output
1080p	Full HD — highest quality output

---

📥 Request Examples

cURL

# Flash model (default) — single source image
curl -X POST "https://api.ideal.house/api/v1/imageToVideo/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "duration": 5,
    "resolution": "720p",
    "modelType": "Flash",
    "prompt": "Gentle camera zoom in with soft lighting"
  }'

# Base model with audio — single source image
curl -X POST "https://api.ideal.house/api/v1/imageToVideo/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room.jpg",
    "duration": 5,
    "resolution": "1080p",
    "modelType": "Base",
    "generateAudio": true,
    "prompt": "Peaceful living room ambiance"
  }'

# First-last frame mode — specify both first and last frame
curl -X POST "https://api.ideal.house/api/v1/imageToVideo/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/room-day.jpg",
    "lastImageUrl": "https://example.com/room-night.jpg",
    "duration": 10,
    "resolution": "720p",
    "modelType": "Flash",
    "prompt": "Smooth day to night transition"
  }'

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class ImageToVideoApiExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY  = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        // Flash model — standard mode
        String requestBody = """
            {
                "imageUrl": "https://example.com/room.jpg",
                "duration": 5,
                "resolution": "720p",
                "modelType": "Flash",
                "prompt": "Gentle camera zoom in with soft lighting"
            }
            """;

        // Base model with audio
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room.jpg",
        //         "duration": 5,
        //         "resolution": "1080p",
        //         "modelType": "Base",
        //         "generateAudio": true,
        //         "prompt": "Peaceful living room ambiance"
        //     }
        //     """;

        // First-last frame mode
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/room-day.jpg",
        //         "lastImageUrl": "https://example.com/room-night.jpg",
        //         "duration": 10,
        //         "resolution": "720p",
        //         "modelType": "Flash",
        //         "prompt": "Smooth day to night transition"
        //     }
        //     """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/imageToVideo/generate")
            .addHeader("APIKEY", API_KEY)
            .addHeader("Content-Type", "application/json")
            .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

# Flash model — single source image
payload = {
    "imageUrl": "https://example.com/room.jpg",
    "duration": 5,
    "resolution": "720p",
    "modelType": "Flash",
    "prompt": "Gentle camera zoom in with soft lighting"
}

# Base model with audio
# payload = {
#     "imageUrl": "https://example.com/room.jpg",
#     "duration": 5,
#     "resolution": "1080p",
#     "modelType": "Base",
#     "generateAudio": True,
#     "prompt": "Peaceful living room ambiance"
# }

# First-last frame mode
# payload = {
#     "imageUrl": "https://example.com/room-day.jpg",
#     "lastImageUrl": "https://example.com/room-night.jpg",
#     "duration": 10,
#     "resolution": "720p",
#     "modelType": "Flash",
#     "prompt": "Smooth day to night transition"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/imageToVideo/generate",
    headers=headers,
    json=payload
)

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createVideoTask() {
  try {
    // Flash model — standard mode
    const payload = {
      imageUrl: 'https://example.com/room.jpg',
      duration: 5,
      resolution: '720p',
      modelType: 'Flash',
      prompt: 'Gentle camera zoom in with soft lighting'
    };

    // Base model with audio:
    // const payload = {
    //   imageUrl: 'https://example.com/room.jpg',
    //   duration: 5,
    //   resolution: '1080p',
    //   modelType: 'Base',
    //   generateAudio: true,
    //   prompt: 'Peaceful living room ambiance'
    // };

    // First-last frame mode:
    // const payload = {
    //   imageUrl: 'https://example.com/room-day.jpg',
    //   lastImageUrl: 'https://example.com/room-night.jpg',
    //   duration: 10,
    //   resolution: '720p',
    //   modelType: 'Flash',
    //   prompt: 'Smooth day to night transition'
    // };

    const response = await axios.post(
      `${BASE_URL}/api/v1/imageToVideo/generate`,
      payload,
      {
        headers: {
          'APIKEY': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    const taskId = response.data.data;
    console.log('Task ID:', taskId);
    return taskId;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createVideoTask();

---

📤 Response

Success Response

{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}

Field	Type	Description
code	integer	0 indicates success
message	string	Response message
data	long	The unique task ID for polling results

---

2. Get Task Result

Retrieves the current status and output of a previously created image-to-video task.

Endpoint

GET /api/v1/imageToVideo/result

Request Headers

Header	Required	Description
APIKEY	✅ Yes	Your API authentication key

Query Parameters

Parameter	Type	Required	Description
taskId	long	✅ Yes	The task ID returned from the create task endpoint

---

📥 Request Examples

cURL

curl -X GET "https://api.ideal.house/api/v1/imageToVideo/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class ImageToVideoResultExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY  = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        long taskId = 1234567890123456789L;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/imageToVideo/result?taskId=" + taskId)
            .addHeader("APIKEY", API_KEY)
            .get()
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests
import time

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY
}

task_id = 1234567890123456789

# Poll until task is complete
while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/imageToVideo/result",
        headers=headers,
        params={"taskId": task_id}
    )

    data = response.json()
    result = data.get("data", {})
    status = result.get("status")

    print(f"Status: {status}, Progress: {result.get('percentage')}%, Queue: {result.get('waitNumber')}")

    if status in ("Success", "Failed"):
        break

    time.sleep(5)  # Poll every 5 seconds (video generation takes longer)

if status == "Success":
    output = result["output"]
    print("Video URL:", output["resultUrl"])
    print("Cover Image:", output["cover"])
else:
    print("Task failed")

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/imageToVideo/result`,
      {
        headers,
        params: { taskId }
      }
    );

    const result = response.data.data;
    const { status, percentage, waitNumber } = result;

    console.log(`Status: ${status} | Progress: ${percentage}% | Queue: ${waitNumber}`);

    if (['Success', 'Failed'].includes(status)) {
      if (status === 'Success') {
        console.log('Video URL:', result.output.resultUrl);
        console.log('Cover Image:', result.output.cover);
        console.log('Resolution:', result.output.width, 'x', result.output.height);
      } else {
        console.log('Task failed');
      }
      break;
    }

    // Wait 5 seconds before next poll (video tasks take longer)
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

pollResult(1234567890123456789n);

---

📤 Response

Success Response (Task Completed — Standard Mode)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "duration": 5,
      "resolution": "720p",
      "modelType": "Flash",
      "prompt": "Gentle camera zoom in with soft lighting"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/video_result.mp4",
      "cover": "https://cdn.ideal.house/output/video_cover.jpg",
      "width": 1280,
      "height": 720
    }
  }
}

Success Response (Task Completed — First-Last Frame Mode)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": "https://example.com/room-day.jpg",
      "lastImageUrl": "https://example.com/room-night.jpg",
      "duration": 10,
      "resolution": "720p",
      "modelType": "Flash",
      "prompt": "Smooth day to night transition"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/video_result.mp4",
      "cover": "https://cdn.ideal.house/output/video_cover.jpg",
      "width": 1280,
      "height": 720
    }
  }
}

Response (Task Processing / In Queue)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Processing",
    "waitNumber": 2,
    "percentage": 30,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "duration": 5,
      "resolution": "720p",
      "modelType": "Flash"
    },
    "output": null
  }
}

Response (Task Failed)

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Failed",
    "waitNumber": 0,
    "percentage": 0,
    "input": {
      "imageUrl": "https://example.com/room.jpg",
      "duration": 5,
      "resolution": "720p",
      "modelType": "Flash"
    },
    "output": null
  }
}

Response Fields

Field	Type	Description
id	long	Task unique identifier
status	string	Current task status (see Task Status)
waitNumber	integer	Number of tasks ahead in the queue (0 means currently processing)
percentage	integer	Task completion percentage (0–100)
input	object	The original input parameters of the task
input.imageUrl	string	Source image URL (first frame in first-last mode)
input.lastImageUrl	string	Last frame image URL (only present in first-last frame mode)
input.duration	integer	Video duration in seconds (5 or 10)
input.resolution	string	Video resolution (480p, 720p, or 1080p)
input.modelType	string	Model type used (Flash or Base)
input.generateAudio	boolean	Whether audio generation was enabled (Base model only)
input.prompt	string	Text prompt (if provided)
output	object	Generation result (only available when status is Success)
output.resultUrl	string	URL to the generated video file
output.cover	string	URL to the video cover / thumbnail image
output.width	integer	Video width in pixels
output.height	integer	Video height in pixels

---

📊 Task Status

Status	Description
Unprocessed	Task has been created but not yet started
Processing	Task is currently being processed
Success	Task completed successfully — video output is available
Failed	Task failed due to an error

💡 Polling Recommendation: Video generation takes longer than image tasks. Poll the result endpoint every 5–10 seconds to avoid excessive requests.

---

❌ Error Responses

All error responses share the same JSON structure:

{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

Error Code Reference

Code	Name	Description	Suggested Action
1001	FAILED	Request failed (generic error)	Check the message field for specific error details
1003	INTERNAL_ERROR	Internal server error	Retry after a short delay; contact support if it persists
1011	PARAM_ERROR	Request parameter error — e.g., invalid modelType, resolution, or duration combination	Verify all required parameters are provided and correctly formatted
5002	API_KEY_INVALID	Invalid or missing API Key	Ensure the APIKEY header is present and the value is correct
9010	SCAN_TEXT_ERROR	Text prompt failed content review	Modify the prompt to remove any sensitive or prohibited content
9038	PROHIBITED_CONTENT	Generated output image contains prohibited content	Adjust prompt/style/inputs and retry
9051	COINS_NOT_ENOUGH	Insufficient coins / credits	Top up your account credits and retry

📄 For the complete list of common API error codes, refer to the Error Code Reference.

---

🔄 Recommended Integration Flow

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Prepare:                                               │
│    - imageUrl [required]                                │
│    - duration: 5 or 10 [required]                       │
│    - resolution: 480p / 720p / 1080p [required]         │
│    - modelType: "Flash" (default) or "Base" [optional]  │
│    - generateAudio: true/false (Base only) [optional]   │
│    - lastImageUrl (first-last frame mode) [optional]    │
│    - prompt [optional]                                  │
│                                                         │
│  1. POST /api/v1/imageToVideo/generate                  │
│     → Receive taskId                                    │
│                                                         │
│  2. Wait 5–10 seconds (video tasks take longer)         │
│                                                         │
│  3. GET /api/v1/imageToVideo/result?taskId={taskId}     │
│     → Check status field                               │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Unprocessed" or "Processing"       │   │
│     │   → waitNumber: position in queue             │   │
│     │   → percentage: current progress              │   │
│     │   → Repeat step 2 & 3                         │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Success"                           │   │
│     │   → output.resultUrl: generated video         │   │
│     │   → output.cover: video cover thumbnail       │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
│     ┌──────────────────────────────────────────────┐   │
│     │ status == "Failed"                            │   │
│     │   → Handle error accordingly                  │   │
│     └──────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

© Ideal House AI — All rights reserved.