Documentazione API di conversione di immagini in video#

URL di base: https://api.ideal.house
Versione: v1
Aggiornato: 2026-03-25

📖 Panoramica#

API di conversione di immagini in video consente di generare video tramite intelligenza artificiale da una singola immagine originale, oppure specificando sia un'immagine del primo fotogramma sia una dell'ultimo fotogramma per controllare l'inizio e la fine del video generato. Il flusso di lavoro è asincrono e prevede due passaggi:

Crea un'attività — Invia le immagini, il tipo di modello, la durata e la risoluzione, quindi ricevi un taskId.
Interroga periodicamente i risultati — Usa il taskId per interrogare lo stato dell'attività e recuperare il video generato.

🔐 Autenticazione#

Tutte le richieste API devono essere autenticate con una chiave API.

Includi la chiave API nell'intestazione della richiesta:

Intestazione	Valore
`APIKEY`	`your_api_key_here`

⚠️ Conserva la chiave API in sicurezza. Non esporla nel codice lato client o in repository pubblici.

💰 Detrazione dei crediti#

[!WARNING] 🪙 I crediti vengono detratti in base a modelType, resolution, duration selezionati e all'abilitazione di generateAudio, alla creazione riuscita dell'attività. Se alla fine l'attività non riesce, i crediti detratti vengono rimborsati automaticamente sul tuo account.
Un saldo di crediti insufficiente restituisce il codice di errore 9051. 📄 Consulta il Riferimento delle detrazioni dei crediti.

Modello Flash (modelType: "Flash", predefinito):

Risoluzione	Durata	Crediti detratti
`480p`	`5s`	10 crediti
`480p`	`10s`	20 crediti
`720p`	`5s`	20 crediti
`720p`	`10s`	40 crediti
`1080p`	`5s`	40 crediti
`1080p`	`10s`	80 crediti

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

Risoluzione	Durata	Crediti detratti
`480p`	`5s`	8 crediti
`480p`	`10s`	16 crediti
`720p`	`5s`	16 crediti
`720p`	`10s`	32 crediti
`1080p`	`5s`	32 crediti
`1080p`	`10s`	64 crediti

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

Risoluzione	Durata	Crediti detratti
`480p`	`5s`	16 crediti
`480p`	`10s`	32 crediti
`720p`	`5s`	32 crediti
`720p`	`10s`	64 crediti
`1080p`	`5s`	64 crediti
`1080p`	`10s`	128 crediti

📌 Endpoint API#

1. Crea un'attività di conversione di immagini in video#

Crea una nuova attività di generazione di video da immagini con intelligenza artificiale e restituisce un taskId univoco per le interrogazioni periodiche.

Endpoint

Testo semplice

POST /api/v1/imageToVideo/generate

Intestazioni della richiesta

Intestazione	Obbligatoria	Descrizione
`APIKEY`	✅ Sì	La tua chiave di autenticazione API
`Content-Type`	✅ Sì	`application/json`

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`imageUrl`	`string`	✅ Sì	URL dell'immagine originale. Nella modalità primo-ultimo fotogramma, funge da primo fotogramma
`duration`	`integer`	✅ Sì	Durata del video in secondi. Enumerazione: `5`, `10`
`resolution`	`string`	✅ Sì	Risoluzione del video risultante. Enumerazione: `480p`, `720p`, `1080p`
`modelType`	`string`	❌ Facoltativo	Tipo di modello da usare per la generazione. Enumerazione: `Flash`, `Base`. Valore predefinito: `Flash`
`generateAudio`	`boolean`	❌ Facoltativo	Se generare audio di sottofondo per il video. Applicabile soltanto quando `modelType` è `Base`. Valore predefinito: `false`
`prompt`	`string`	❌ Facoltativo	Prompt testuale per orientare stile e movimento nella generazione del video
`lastImageUrl`	`string`	❌ Facoltativo	URL dell'immagine dell'ultimo fotogramma. Quando fornita, abilita la modalità primo-ultimo fotogramma: il video passerà da `imageUrl` (primo fotogramma) a `lastImageUrl` (ultimo fotogramma)

💡 Modalità primo-ultimo fotogramma: se viene fornito lastImageUrl, API genera un video che passa fluidamente dall'immagine del primo fotogramma (imageUrl) all'immagine dell'ultimo fotogramma (lastImageUrl), consentendo un controllo preciso sull'inizio e sulla fine del video.

🖼️ Requisiti delle immagini: l'immagine del primo fotogramma e quella facoltativa dell'ultimo devono usare JPG/JPEG, PNG o WebP. Ogni immagine non deve superare 20 MB, con dimensioni da 128 × 128 px fino a 6,000 × 6,000 px (estremi inclusi). Prima dell'elaborazione, le immagini che superano le dimensioni massime in pixel vengono ridotte automaticamente in modo proporzionale per rientrare in 6,000 × 6,000 px. Le URLs delle immagini devono essere direttamente accessibili dal server API.

Tipi di modello

Valore	Descrizione
`Flash`	Predefinito. Generazione più rapida con output di alta qualità
`Base`	Modello alternativo — supporta la generazione facoltativa di audio tramite intelligenza artificiale (`generateAudio`)

Opzioni della durata

Valore	Descrizione
`5`	Video di 5 secondi
`10`	Video di 10 secondi

Opzioni della risoluzione

Valore	Descrizione
`480p`	Definizione standard — elaborazione più rapida
`720p`	Alta definizione — output di qualità maggiore
`1080p`	Full HD — output della massima qualità

📥 Esempi di richiesta#

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

📤 Risposta#

Risposta di successo

json

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

Campo	Tipo	Descrizione
`code`	`integer`	`0` indica il successo
`message`	`string`	Messaggio della risposta
`data`	`long`	Identificatore univoco dell'attività per interrogare periodicamente i risultati

2. Ottieni il risultato dell'attività#

Recupera lo stato e l'output correnti di un'attività di conversione di immagini in video creata in precedenza.

Endpoint

Testo semplice

GET /api/v1/imageToVideo/result

Intestazioni della richiesta

Intestazione	Obbligatoria	Descrizione
`APIKEY`	✅ Sì	La tua chiave di autenticazione API

Parametri di interrogazione

Parametro	Tipo	Obbligatorio	Descrizione
`taskId`	`long`	✅ Sì	Identificatore dell'attività restituito dall'endpoint di creazione dell'attività

📥 Esempi di richiesta#

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

📤 Risposta#

Risposta di successo (attività completata — modalità standard)

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

Risposta di successo (attività completata — modalità primo-ultimo fotogramma)

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

Risposta (attività in elaborazione / in coda)

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

Risposta (attività non riuscita)

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

Campi della risposta

Campo	Tipo	Descrizione
`id`	`long`	Identificatore univoco dell'attività
`status`	`string`	Stato corrente dell'attività (vedi Stato dell'attività)
`waitNumber`	`integer`	Numero di attività precedenti in coda (`0` significa attualmente in elaborazione)
`percentage`	`integer`	Percentuale di completamento dell'attività (`0–100`)
`input`	`object`	Parametri di input originali dell'attività
`input.imageUrl`	`string`	URL dell'immagine originale (primo fotogramma nella modalità primo-ultimo)
`input.lastImageUrl`	`string`	URL dell'immagine dell'ultimo fotogramma (presente soltanto nella modalità primo-ultimo fotogramma)
`input.duration`	`integer`	Durata del video in secondi (`5` o `10`)
`input.resolution`	`string`	Risoluzione del video (`480p`, `720p` o `1080p`)
`input.modelType`	`string`	Tipo di modello usato (`Flash` o `Base`)
`input.generateAudio`	`boolean`	Se la generazione audio era abilitata (soltanto modello Base)
`input.prompt`	`string`	Prompt testuale (se fornito)
`output`	`object`	Risultato della generazione (disponibile soltanto quando `status` è `Success`)
`output.resultUrl`	`string`	URL del file video generato
`output.cover`	`string`	URL dell'immagine di copertina / miniatura del video
`output.width`	`integer`	Larghezza del video in pixel
`output.height`	`integer`	Altezza del video in pixel

📊 Stato dell'attività#

Stato	Descrizione
`Unprocessed`	L'attività è stata creata ma non è ancora iniziata
`Processing`	L'attività è attualmente in elaborazione
`Success`	L'attività è stata completata correttamente — il video risultante è disponibile
`Failed`	L'attività non è riuscita a causa di un errore

Interroga lo stato ogni 3-5 secondi. Consulta i Limiti delle attività API.

❌ Risposte di errore#

Tutte le risposte di errore condividono la stessa struttura JSON:

json

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

Riferimento dei codici di errore#

Codice	Nome	Descrizione	Azione suggerita
`1001`	`FAILED`	Richiesta non riuscita (errore generico)	Controlla il campo `message` per i dettagli specifici dell'errore
`1003`	`INTERNAL_ERROR`	Errore interno del server	Riprova dopo una breve attesa; contatta l'assistenza se il problema persiste
`1011`	`PARAM_ERROR`	Errore nei parametri della richiesta — e.g., combinazione non valida di `modelType`, `resolution` o `duration`	Verifica che tutti i parametri obbligatori siano forniti e formattati correttamente
`5002`	`API_KEY_INVALID`	Chiave API non valida o mancante	Assicurati che l'intestazione `APIKEY` sia presente e che il valore sia corretto
`9010`	`SCAN_TEXT_ERROR`	Il prompt testuale non ha superato la verifica dei contenuti	Modifica il prompt per rimuovere eventuali contenuti sensibili o vietati
`9038`	`PROHIBITED_CONTENT`	L'immagine generata contiene contenuti vietati	Modifica prompt/stile/input e riprova
`9051`	`COINS_NOT_ENOUGH`	Monete / crediti insufficienti	Ricarica i crediti dell'account e riprova

📄 Per l'elenco completo dei codici di errore API comuni, consulta il Riferimento dei codici di errore.