Istruzioni per l'integrazione dell'API HappyHorse Videos

Questo documento descrive come integrare l’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 attraverso l’endpoint unificato /happyhorse/videos e il parametro action.

Procedura di richiesta

Per utilizzare l’API HappyHorse Videos, innanzitutto ottieni il tuo API Token dalla console Ace Data Cloud e conservalo per uso futuro.

Se non hai ancora effettuato l’accesso o la registrazione, 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 necessità di richiederne uno separatamente per ciascun servizio. Alla prima richiesta verrà assegnato credito gratuito, per permetterti di provare il servizio gratuitamente; quando il credito è insufficiente, 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 video da testo, action predefinita, supporta happyhorse-1.0-t2v e happyhorse-1.1-t2v, è obbligatorio passare prompt.
image_to_video: generazione video da immagine del primo fotogramma, supporta happyhorse-1.0-i2v e happyhorse-1.1-i2v, è obbligatorio passare image_url.
reference_to_video: generazione video da immagini di riferimento, supporta happyhorse-1.0-r2v e happyhorse-1.1-r2v, è obbligatorio passare prompt e 1–9 image_urls.
video_edit: editing video, supporta happyhorse-1.0-video-edit, è obbligatorio passare prompt e video_url, ed è possibile passare ulteriormente 0–5 immagini di riferimento image_urls.

Ogni azione utilizza per impostazione predefinita il modello 1.1; video_edit al momento dispone solo di happyhorse-1.0-video-edit.

Utilizzo di base

Per la generazione video da testo è necessario fornire soltanto prompt; è anche possibile specificare parametri come resolution, ratio, duration e così via:

{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Un esempio del risultato restituito è il seguente:

{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}

Descrizione dei campi:

success: indica se questa richiesta ha avuto esito positivo.
task_id: ID del task lato Ace Data Cloud, utilizzabile per interrogare lo stato del task.
trace_id: ID di tracciamento di questa richiesta, utilizzato per risolvere i problemi.
data: elenco dei risultati video.
- id: ID del task lato HappyHorse.
- video_url: indirizzo del link CDN del video generato.
- state: stato del task, può essere pending / succeeded / error.
- duration: durata del video fatturata, in secondi; per video_edit è la durata complessiva dei video di input e output.
- resolution: risoluzione di output.
- ratio: rapporto larghezza-altezza di output.

Il codice CURL corrispondente è il seguente:

curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'

Il codice Python corrispondente è il seguente:

import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Generazione 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à per quanto possibile l’immagine del primo fotogramma, pertanto questa azione non richiede il passaggio di ratio.

{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}

Generazione video da immagini di riferimento

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

{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Editing video

Quando si utilizza video_edit, è obbligatorio passare il video da modificare video_url e l’intento di modifica prompt. Le image_urls opzionali verranno utilizzate come immagini di riferimento, ad esempio per il cambio di abbigliamento, il trasferimento di stile o la sostituzione locale. audio_setting può essere facoltativamente auto oppure origin, dove origin indica il mantenimento dell’audio del video originale.

{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}

Callback asincrono

La generazione di 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 tale indirizzo:

{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}

Il risultato restituito immediatamente è il seguente:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

Se si desidera solo eseguire il polling, senza necessità di callback, è anche possibile passare "async": true, quindi 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: l’addebito avviene in base alla durata complessiva del video in input e del video in output; la durata effettivamente fatturata si basa sulle statistiche dopo il completamento dell’attività.

Le attività non riuscite non vengono fatturate e non consumano il credito gratuito.

Gestione degli errori

Quando si verifica un problema nella richiesta, l’API restituirà il codice di errore e la relativa descrizione; quelli comuni sono i seguenti:

400: i parametri della richiesta non sono corretti, 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 viene rifiutato perché rilevato dalla revisione dei contenuti.
429: richieste troppo frequenti, è stato attivato il limite di frequenza; riprovare più tardi.
500: errore interno del server o generazione non riuscita.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Istruzioni per l'integrazione dell'API HappyHorse Videos

Procedura di richiesta

Tipi di operazione

Utilizzo di base

Generazione video da immagine del primo fotogramma

Generazione video da immagini di riferimento

Editing video

Callback asincrono

Informazioni sulla fatturazione

Gestione degli errori

​Procedura di richiesta

​Tipi di operazione

​Utilizzo di base

​Generazione video da immagine del primo fotogramma

​Generazione video da immagini di riferimento

​Editing video

​Callback asincrono

​Informazioni sulla fatturazione

​Gestione degli errori

Procedura di richiesta

Tipi di operazione

Utilizzo di base

Generazione video da immagine del primo fotogramma

Generazione video da immagini di riferimento

Editing video

Callback asincrono

Informazioni sulla fatturazione

Gestione degli errori