Documentación de la API de imagen a vídeo#

URL base: https://api.ideal.house
Versión: v1
Actualizado: 2026-03-25

📖 Descripción general#

La API de imagen a vídeo te permite generar videos impulsados por IA a partir de una única imagen de origen, o especificando tanto una imagen de primer fotograma como de último fotograma para controlar el inicio y el final del video generado. El flujo de trabajo es asíncrono y consta de dos pasos:

Crear una tarea — Envía tu(s) imagen(es), tipo de modelo, duración y resolución, y recibirás un taskId.
Consultar resultados — Usa el taskId para consultar el estado de la tarea y obtener el video generado.

🔐 Autenticación#

Todas las solicitudes a la API deben autenticarse mediante una Clave de API.

Incluye tu Clave de API en el encabezado de la solicitud:

Encabezado	Valor
`APIKEY`	`your_api_key_here`

⚠️ Mantén tu Clave de API segura. No la expongas en código del lado del cliente ni en repositorios públicos.

💰 Deducción de créditos#

[!WARNING] 🪙 Los créditos se descuentan según el modelType, resolution, duration seleccionados y si generateAudio está habilitado al crear la tarea exitosamente. Si la tarea finalmente falla, los créditos descontados se reembolsarán automáticamente a tu cuenta.
Los créditos insuficientes devolverán el código de error 9051. 📄 Consulta la Referencia de Deducción de Créditos.

Modelo Flash (modelType: "Flash", predeterminado):

Resolución	Duración	Créditos Descontados
`480p`	`5s`	10 créditos
`480p`	`10s`	20 créditos
`720p`	`5s`	20 créditos
`720p`	`10s`	40 créditos
`1080p`	`5s`	40 créditos
`1080p`	`10s`	80 créditos

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

Resolución	Duración	Créditos Descontados
`480p`	`5s`	8 créditos
`480p`	`10s`	16 créditos
`720p`	`5s`	16 créditos
`720p`	`10s`	32 créditos
`1080p`	`5s`	32 créditos
`1080p`	`10s`	64 créditos

Modelo Base con audio (modelType: "Base", generateAudio: true):

Resolución	Duración	Créditos Descontados
`480p`	`5s`	16 créditos
`480p`	`10s`	32 créditos
`720p`	`5s`	32 créditos
`720p`	`10s`	64 créditos
`1080p`	`5s`	64 créditos
`1080p`	`10s`	128 créditos

📌 Endpoints de la API#

1. Crear tarea de Imagen a Video#

Crea una nueva tarea de generación de video a partir de imágenes con IA y devuelve un taskId único para realizar polling.

Endpoint

Texto plano

POST /api/v1/imageToVideo/generate

Encabezados de la solicitud

Encabezado	Obligatorio	Descripción
`APIKEY`	✅ Sí	Tu clave de autenticación API
`Content-Type`	✅ Sí	`application/json`

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`imageUrl`	`string`	✅ Sí	URL de la imagen de origen. En modo primer-último fotograma, esto sirve como el primer fotograma
`duration`	`integer`	✅ Sí	Duración del video en segundos. Enum: `5`, `10`
`resolution`	`string`	✅ Sí	Resolución de salida del video. Enum: `480p`, `720p`, `1080p`
`modelType`	`string`	❌ Opcional	Tipo de modelo a usar para la generación. Enum: `Flash`, `Base`. Predeterminado `Flash`
`generateAudio`	`boolean`	❌ Opcional	Indica si se debe generar audio de fondo para el video. Solo aplicable cuando `modelType` es `Base`. Predeterminado `false`
`prompt`	`string`	❌ Opcional	Indicación en texto para guiar el estilo y el movimiento de la generación del video
`lastImageUrl`	`string`	❌ Opcional	URL de la imagen del último fotograma. Al proporcionarla, se habilita el modo primer-último fotograma: el video transicionará desde `imageUrl` (primer fotograma) hasta `lastImageUrl` (último fotograma)

💡 Modo primer-último fotograma: Si se proporciona lastImageUrl, la API genera un video que transiciona suavemente desde la imagen del primer fotograma (imageUrl) hasta la imagen del último fotograma (lastImageUrl), dándote un control preciso sobre el inicio y el final del video.

🖼️ Requisitos de imagen: Las imágenes del primer fotograma y del último fotograma opcional deben usar los formatos JPG/JPEG, PNG o WebP. Cada imagen no debe superar 20 MB, con dimensiones desde 128 × 128 px hasta 6,000 × 6,000 px (inclusive). Las imágenes que excedan las dimensiones máximas en píxeles se reducirán proporcionalmente automáticamente para ajustarse a 6,000 × 6,000 px antes del procesamiento. Los URLs de las imágenes deben ser directamente accesibles por el servidor de la API.

Tipos de Modelo

Valor	Descripción
`Flash`	Predeterminado. Mayor velocidad de generación con salida de alta calidad
`Base`	Modelo alternativo — admite generación opcional de audio con IA (`generateAudio`)

Opciones de duración

Valor	Descripción
`5`	vídeo de 5 segundos
`10`	video de 10 segundos

Opciones de resolución

Valor	Descripción
`480p`	Definición estándar — procesamiento más rápido
`720p`	Alta definición — mayor calidad de salida
`1080p`	Full HD — máxima calidad de salida

📥 Ejemplos de solicitud#

cURL

bash

# 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)

java

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)

python

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)

javascript

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();

📤 Respuesta#

Respuesta de Éxito

json

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

Campo	Tipo	Descripción
`code`	`integer`	`0` indica éxito
`message`	`string`	Mensaje de la respuesta
`data`	`long`	El ID único de la tarea para consultar los resultados

2. Obtener resultado de la tarea#

Recupera el estado actual y la salida de una tarea de imagen a video creada previamente.

Endpoint

Texto plano

GET /api/v1/imageToVideo/result

Encabezados de la solicitud

Encabezado	Obligatorio	Descripción
`APIKEY`	✅ Sí	Tu clave de autenticación API

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`taskId`	`long`	✅ Sí	El ID de la tarea devuelto por el endpoint de creación

📥 Ejemplos de solicitud#

cURL

bash

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

Java (OkHttp)

java

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)

python

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)

javascript

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);

📤 Respuesta#

Respuesta exitosa (tarea completada — modo estándar)

json

{
  "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
    }
  }
}

Respuesta exitosa (tarea completada — modo primer-último fotograma)

json

{
  "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
    }
  }
}

Respuesta (tarea en procesamiento / en cola)

json

{
  "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
  }
}

Respuesta (tarea fallida)

json

{
  "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
  }
}

Campos de Respuesta

Campo	Tipo	Descripción
`id`	`long`	Identificador único de la tarea
`status`	`string`	Estado actual de la tarea (ver Estado de Tarea)
`waitNumber`	`integer`	Número de tareas por delante de la tarea actual en la cola (`0` significa que se está procesando en este momento)
`percentage`	`integer`	Porcentaje de finalización de la tarea (`0–100`)
`input`	`object`	Los parámetros de entrada originales de la tarea
`input.imageUrl`	`string`	URL de la imagen de origen (primer fotograma en modo primer-último)
`input.lastImageUrl`	`string`	Última imagen de fotograma URL (solo presente en modo primer-último fotograma)
`input.duration`	`integer`	Duración del video en segundos (`5` o `10`)
`input.resolution`	`string`	Resolución del video (`480p`, `720p` o `1080p`)
`input.modelType`	`string`	Tipo de modelo utilizado (`Flash` o `Base`)
`input.generateAudio`	`boolean`	Si se habilitó la generación de audio (solo modelo Base)
`input.prompt`	`string`	Prompt de texto (si se proporcionó)
`output`	`object`	Resultado de la generación (solo disponible cuando `status` es `Success`)
`output.resultUrl`	`string`	URL al archivo de video generado
`output.cover`	`string`	URL a la imagen de portada / miniatura del video
`output.width`	`integer`	Ancho del video en píxeles
`output.height`	`integer`	Altura del video en píxeles

📊 Estado de la tarea#

Estado	Descripción
`Unprocessed`	La tarea se ha creado pero aún no se ha iniciado
`Processing`	La tarea se está procesando actualmente
`Success`	Tarea completada exitosamente; la salida de video está disponible
`Failed`	La tarea falló debido a un error

Consulta cada 3-5 segundos. Consulta Límite de tareas de la API.

❌ Respuestas de error#

Todas las respuestas de error comparten la misma estructura JSON:

json

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

Referencia de Códigos de Error#

Código	Nombre	Descripción	Acción Sugerida
`1001`	`FAILED`	Error genérico en la solicitud	Comprueba el campo `message` para ver los detalles específicos del error
`1003`	`INTERNAL_ERROR`	Error interno del servidor	Reintentar después de un breve retraso; contactar soporte si persiste
`1011`	`PARAM_ERROR`	Error en parámetro de solicitud — por ejemplo, combinación inválida de `modelType`, `resolution` o `duration`	Verifica que todos los parámetros requeridos estén presentes y tengan el formato correcto
`5002`	`API_KEY_INVALID`	Clave API inválida o ausente	Asegúrate de que el encabezado `APIKEY` está presente y que el valor es correcto
`9010`	`SCAN_TEXT_ERROR`	El prompt de texto no pasó la revisión de contenido	Modifica el prompt para eliminar cualquier contenido sensible o prohibido
`9038`	`PROHIBITED_CONTENT`	La imagen de salida generada contiene contenido prohibido	Ajusta la sugerencia/estilo/entradas y reintenta
`9051`	`COINS_NOT_ENOUGH`	Monedas / créditos insuficientes	Recarga los créditos de tu cuenta e intenta de nuevo

📄 Para la lista completa de códigos de error comunes de la API, consulta la Referencia de códigos de error.