> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Istruzioni per l'integrazione con l'API di Generazione Video Sora > Sora Video Generation 集成指南 - XHuoAPI Questo documento illustra le istruzioni per l'integrazione con l'API di Generazione Video Sora, tramite la quale è possibile generare video ufficiali Sora inserendo parametri personalizzati. Questa API supporta due modalità di versione: * **Versione 1 (modalità classica)**: supporta i parametri `duration` (10/15/25 secondi), `orientation` (orizzontale/verticale), `size` (small/large qualità), immagini di riferimento `image_urls`, link del personaggio `character_url` e altri. * **Versione 2 (modalità partner)**: supporta i parametri `seconds` (4/8/12 secondi), risoluzione a livello di pixel `size` (ad esempio 1280x720), immagini di riferimento `input_reference` e altri. ## Procedura di richiesta Per utilizzare l'API, è necessario prima richiedere il servizio corrispondente sulla pagina [Sora Videos Generation API](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). Dopo aver aperto la pagina, cliccare sul pulsante "Acquire", come mostrato nell'immagine: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Se non si è ancora effettuato l'accesso o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; dopo il login si tornerà automaticamente alla pagina corrente. Alla prima richiesta viene offerto un credito gratuito per utilizzare l'API senza costi. ## Uso base (Versione 1) Per prima cosa, vediamo il modo base di utilizzo della Versione 1: inserire il prompt `prompt`, un array di URL di immagini di riferimento `image_urls` e il modello `model` per ottenere il risultato elaborato. Il contenuto specifico è il seguente:

Qui impostiamo gli header della richiesta, tra cui: * `accept`: indica il formato di risposta desiderato, qui impostato su `application/json` (formato JSON). * `authorization`: la chiave API per chiamare l'API, selezionabile direttamente dopo la richiesta. Inoltre, impostiamo il corpo della richiesta (Request Body), che include: * `model`: modello per generare il video, supporta `sora-2` (modalità standard) e `sora-2-pro` (modalità HD). `sora-2-pro` supporta video di 25 secondi, mentre `sora-2` solo 10 o 15 secondi. * `size`: qualità del video, `small` per qualità standard, `large` per HD (solo Versione 1). * `duration`: durata del video, supporta 10, 15, 25 secondi; 25 secondi è supportato solo da `sora-2-pro` (solo Versione 1). * `orientation`: orientamento del video, supporta `landscape` (orizzontale), `portrait` (verticale) (solo Versione 1). * `image_urls`: array di URL di immagini di riferimento per generare video da immagini (solo Versione 1). * `character_url`: link del personaggio, il video non deve contenere persone reali (solo Versione 1). * `character_start`/`character_end`: secondi di inizio e fine comparsa del personaggio, intervallo 1-3 secondi (solo Versione 1). * `prompt`: prompt testuale (obbligatorio). * `callback_url`: URL per callback asincrono. * `version`: versione API, `"1.0"` (default) o `"2.0"`. Dopo la selezione, si genera automaticamente il codice corrispondente a destra, come mostrato:

Cliccando il pulsante "Try" si può testare la chiamata; come nell'immagine, otteniamo il seguente risultato: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Il risultato restituito contiene vari campi, descritti di seguito: * `success`: stato del task di generazione video. * `task_id`: ID del task di generazione video. * `trace_id`: ID di tracciamento della richiesta. * `data`: lista dei risultati del task di generazione video. * `id`: ID del video generato. * `video_url`: URL del video generato. * `state`: stato del task. Come si vede, abbiamo ottenuto le informazioni del video desiderato; basta usare l'URL contenuto in `data` per scaricare il video Sora generato. Se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2" }' ``` ## Task di generazione video da immagine (Versione 1) Per generare un video da immagine, è necessario passare il parametro `image_urls` con gli URL delle immagini di riferimento, specificando: * `image_urls`: array di URL delle immagini di riferimento per il task di generazione video da immagine. Non inviare immagini con volti reali, altrimenti il task potrebbe fallire. Esempio di compilazione:

Dopo la compilazione si genera automaticamente il codice:

Codice corrispondente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Eseguendo la chiamata si ottiene subito un risultato: ``` { "success": true, "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a", "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172", "data": [ { "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Come si vede, il risultato è un video generato da immagine, simile a quanto mostrato sopra. ## Task di generazione video con personaggio (Versione 1) Per generare un video con personaggio, è necessario passare il parametro `character_url` con il link video per creare il personaggio; il video non deve contenere persone reali, altrimenti il task fallirà. Si possono specificare i seguenti parametri: * `character_url`: link video per creare il personaggio, senza persone reali. Esempio di compilazione:

Dopo la compilazione si genera automaticamente il codice:

Codice corrispondente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "small", "duration": 10, "orientation": "landscape", "prompt": "cat running on the river", "character_url": "https://cdn.xhuoapi.ai/pdidf5.mp4", "model": "sora-2", "character_end": 3, "character_start": 1 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Eseguendo la chiamata si ottiene subito un risultato: ``` { "success": true, "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259", "trace_id": "b7992643-9207-40d6-956b-7577728acc67", "data": [ { "id": "sora-2:task_01k8ykrztefavaypw6xanw305b", "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4", "state": "succeeded" } ] } ``` Come si vede, il risultato è un video generato con personaggio, simile a quanto mostrato sopra. ## Modalità Versione 2.0 Oltre alla modalità Versione 1.0 sopra descritta, questa API supporta anche la modalità Versione 2.0, attivabile impostando il parametro `version` a `"2.0"`. La modalità 2.0 supporta video di durata più breve e controllo della risoluzione a livello di pixel. ### Descrizione parametri Versione 2.0 | Parametro | Tipo | Obbligatorio | Descrizione | | -------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------ | | `version` | string | Sì | Impostare a `"2.0"` | | `prompt` | string | Sì | Prompt per generare il video | | `model` | string | No | `sora-2` (default) o `sora-2-pro` | | `duration` | integer | No | Durata video: `4` (default), `8`, `12` secondi | | `size` | string | No | Risoluzione: `720x1280` (default), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | No | Array di URL immagini di riferimento, viene usata solo la prima immagine, dimensioni devono corrispondere a `size` | | `callback_url` | string | No | URL per callback asincrono | ### Esempio base ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "duration": 8, "size": "1280x720" }' ``` Codice Python corrispondente: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "seconds": 8, "size": "1280x720" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Codice JavaScript corrispondente: ```javascript theme={null} const response = await fetch('https://api.xhuoapi.ai/v1/sora/videos', { method: 'POST', headers: { 'accept': 'application/json', 'authorization': 'Bearer {token}', 'content-type': 'application/json' }, body: JSON.stringify({ version: '2.0', prompt: 'cat running on the river', model: 'sora-2', seconds: 8, size: '1280x720' }) }); const data = await response.json(); console.log(data); ``` Il formato del risultato restituito è identico a quello della Versione 1: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "c0cc8dad-0954-421f-be8d-02eb063b3263", "video_url": "https://platform.cdn.xhuoapi.ai/sora/xxxxx.mp4", "state": "succeeded" } ] } ``` ### Uso di immagini di riferimento (Versione 2.0) Nella modalità Versione 2.0 è possibile passare immagini di riferimento tramite il parametro `image_urls` per guidare la generazione video (viene usata solo la prima immagine): ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "a person walking through a beautiful garden", "model": "sora-2", "duration": 4, "size": "1280x720", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` > **Nota**: la dimensione dell'immagine di riferimento deve corrispondere al parametro `size`. Ad esempio, se `size` è `1280x720`, l'immagine deve avere dimensioni 1280×720. ### Confronto parametri Versione 1.0 e 2.0 | Parametro | Versione 1.0 | Versione 2.0 | | --------------- | --------------------- | --------------------------------------- | | `version` | 1.0 (default) | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 secondi | ✅ 4/8/12 secondi | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ più immagini | ✅ solo la prima immagine | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## Callback asincrono Poiché la generazione video tramite Sora Videos Generation API richiede un tempo relativamente lungo (circa 1-2 minuti), se l'API non risponde rapidamente la connessione HTTP rimane aperta, causando un consumo aggiuntivo di risorse di sistema. Per questo motivo l'API supporta anche callback asincroni. Il flusso è: il client invia la richiesta specificando un campo `callback_url`; l'API risponde immediatamente con un risultato contenente il campo `task_id` che identifica il task. Quando il task è completato, il risultato della generazione video viene inviato tramite POST JSON all'URL `callback_url` specificato dal client, includendo anche il campo `task_id` per associare il risultato al task. Vediamo un esempio pratico. Innanzitutto, il webhook callback è un servizio che può ricevere richieste HTTP; lo sviluppatore deve sostituire con l'URL del proprio server HTTP. Per comodità, qui usiamo un sito pubblico di esempio per webhook [https://webhook.site/](https://webhook.site/), aprendo il sito si ottiene un URL webhook, come mostrato: ![](https://cdn.xhuoapi.ai/cjjfly.png) Copiare questo URL per usarlo come webhook, ad esempio `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`. Poi impostiamo il campo `callback_url` con questo URL e inseriamo gli altri parametri, come mostrato:

Cliccando "Run" si ottiene subito un risultato: ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` Dopo qualche istante, su `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa` si può osservare il risultato della generazione video, come mostrato: ![](https://cdn.xhuoapi.ai/0j7nra.png) Contenuto: ```json theme={null} { "success": true, "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2", "data": [ { "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Come si vede, il risultato contiene il campo `task_id` e altri campi simili a quelli sopra, permettendo di associare il risultato al task tramite ID. ## Gestione errori In caso di errore durante la chiamata API, l'API restituisce un codice e un messaggio di errore corrispondenti. Ad esempio: * `400 token_mismatched`: richiesta errata, probabilmente parametri mancanti o non validi. * `400 api_not_implemented`: richiesta errata, probabilmente parametri mancanti o non validi. * `401 invalid_token`: non autorizzato, token di autorizzazione mancante o non valido. * `429 too_many_requests`: troppe richieste, superato il limite di velocità. * `500 api_error`: errore interno del server. ### Esempio di risposta di errore ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusione Con questo documento avete appreso come utilizzare l'API di Generazione Video Sora per generare video inserendo prompt e immagini di riferimento. Speriamo che questa guida vi aiuti a integrare e utilizzare al meglio l'API. Per qualsiasi domanda, non esitate a contattare il nostro team di supporto tecnico.