Vai al contenuto principale
Questo articolo introduce il metodo di integrazione dell’API HappyHorse Videos. Questa API supporta la generazione di video da testo, la generazione di video da immagine del primo fotogramma, la generazione di video da immagini di riferimento e l’editing video tramite l’endpoint unificato /happyhorse/videos e il parametro action.

Procedura di richiesta

Per utilizzare l’API HappyHorse Videos, ottenere prima il proprio API Token dalla console Ace Data Cloud e conservarlo per l’uso. Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per registrarti e accedere; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ogni servizio. La prima richiesta include crediti gratuiti per provare il servizio gratuitamente; quando i crediti sono insufficienti, puoi ricaricare il saldo generale nella console.
📘 Documentazione completa: HappyHorse Videos API →

Tipi di operazione

action determina la modalità di generazione di questa richiesta:
  • generate: generazione di video da testo, action predefinita, supporta happyhorse-1.0-t2v e happyhorse-1.1-t2v, è necessario passare prompt.
  • image_to_video: generazione di video da immagine del primo fotogramma, supporta happyhorse-1.0-i2v e happyhorse-1.1-i2v, è necessario passare image_url.
  • reference_to_video: generazione di video da immagini di riferimento, supporta happyhorse-1.0-r2v e happyhorse-1.1-r2v, è necessario passare prompt e 1–9 image_urls.
  • video_edit: editing video, supporta happyhorse-1.0-video-edit, è necessario passare prompt e video_url, ed è possibile passare ulteriori 0–5 immagini di riferimento image_urls.
Ogni azione utilizza per impostazione predefinita il modello 1.1; video_edit dispone attualmente solo di happyhorse-1.0-video-edit.

Utilizzo di base

Per la generazione di video da testo è sufficiente fornire prompt; è anche possibile specificare parametri come resolution, ratio, duration e così via:
Un esempio del risultato restituito è il seguente:
Descrizione dei campi:
  • success: indica se questa richiesta è riuscita.
  • task_id: ID dell’attività lato Ace Data Cloud, utilizzabile per interrogare lo stato dell’attività.
  • trace_id: ID di tracciamento di questa richiesta, utilizzato per diagnosticare i problemi.
  • data: elenco dei risultati video.
    • id: ID dell’attività lato HappyHorse.
    • video_url: indirizzo del collegamento CDN del video generato.
    • state: stato dell’attività, può essere pending / succeeded / error.
    • duration: durata del video fatturabile, in secondi; per video_edit è la durata totale dei video di input e output.
    • resolution: risoluzione di output.
    • ratio: rapporto larghezza-altezza di output.
Il codice CURL corrispondente è il seguente:
Il codice Python corrispondente è il seguente:

Generazione di video da immagine del primo fotogramma

Quando si utilizza image_to_video, image_url verrà utilizzato come primo fotogramma del video. Il rapporto larghezza-altezza di output seguirà il più possibile l’immagine del primo fotogramma, pertanto non è necessario passare ratio per questa azione.

Generazione di video da immagini di riferimento

Quando si utilizza reference_to_video, è possibile passare 1–9 immagini di riferimento in image_urls. Nel prompt, è possibile fare riferimento alle immagini nell’ordine corrispondente usando character1, character2 e così via.

Editing video

La durata di output e il formato di video_edit ereditano il video sorgente; passare duration o ratio non li modificherà; anche il formato del video generato da immagine eredita l’immagine sorgente. Il costo di editing viene calcolato in base alla durata totale dei video di input e output. Quando si utilizza video_edit, è necessario passare il video da modificare video_url e l’intento di modifica prompt. Gli image_urls facoltativi verranno utilizzati come immagini di riferimento, ad esempio per cambio di abbigliamento, trasferimento di stile o sostituzione locale. audio_setting può essere facoltativamente auto o origin, dove origin indica di mantenere l’audio originale del video.

Callback asincrono

La generazione del video richiede un certo tempo di elaborazione. Se non si desidera mantenere una connessione lunga in attesa, è possibile passare callback_url; in questo caso l’API restituirà immediatamente task_id e, al completamento dell’attività, effettuerà il POST del risultato finale a questo indirizzo:
Il risultato restituito immediatamente è il seguente:
Se si desidera solo effettuare il polling e non è necessario un callback, è anche possibile passare "async": true e successivamente interrogare il risultato dell’attività tramite HappyHorse Tasks API.

Informazioni sulla fatturazione

HappyHorse addebita in base ai secondi del video in output e alla risoluzione:
  • 720P: a partire da circa $0.105 / secondo.
  • 1080P: a partire da circa $0.18 / secondo.
  • video_edit: addebitato in base alla durata complessiva del video in input e del video in output; la durata effettivamente fatturata è soggetta alle statistiche dopo il completamento dell’attività.
Le attività non riuscite non vengono addebitate e non consumano la quota gratuita.

Gestione degli errori

Quando si verifica un problema con la richiesta, l’API restituirà il codice di errore e la relativa descrizione; quelli comuni sono i seguenti:
  • 400: i parametri della richiesta non sono validi, ad esempio action e model non corrispondono, manca prompt / image_url / video_url, oppure duration supera l’intervallo di 3–15 secondi.
  • 401: autenticazione non riuscita, il token non è valido o non corrisponde all’API.
  • 403: saldo insufficiente, oppure il prompt è stato rifiutato dal controllo dei contenuti.
  • 429: richieste troppo frequenti, limite di velocità attivato; riprovare più tardi.
  • 500: errore interno del server o generazione non riuscita.