> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Istruzioni per l'integrazione dell'API HappyHorse Videos > HappyHorse Video API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) e conservalo per uso futuro. ![](https://cdn.acedata.cloud/dvc3cg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos) ## 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: ```json theme={null} { "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: ```json theme={null} { "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: ```shell theme={null} 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: ```python theme={null} 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`. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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](https://platform.acedata.cloud/documents/happyhorse-tasks). ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.