> ## 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. # Instruções de Integração da API de Geração de Vídeos Sora > Sora Video Generation 集成指南 - XHuoAPI Este documento apresenta as instruções para integração da API de Geração de Vídeos Sora, que permite gerar vídeos oficiais da Sora a partir de parâmetros personalizados. Esta API suporta dois modos de versão: * **Versão 1 (modo clássico)**: suporta parâmetros como `duration` (10/15/25 segundos), `orientation` (paisagem/retrato), `size` (small/large para resolução), imagens de referência `image_urls`, e link de personagem `character_url`. * **Versão 2 (modo parceiro)**: suporta `seconds` (4/8/12 segundos), resolução em pixels `size` (ex: 1280x720), imagens de referência `input_reference`, entre outros. ## Processo de Solicitação Para usar a API, é necessário solicitar o serviço correspondente na página [Sora Videos Generation API](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). Após acessar, clique no botão "Acquire", conforme mostrado: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Se ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde poderá se registrar e entrar. Após o login, retornará automaticamente à página atual. Na primeira solicitação, haverá uma cota gratuita para uso da API. ## Uso Básico (Versão 1) Primeiro, entenda o uso básico da Versão 1, que consiste em fornecer o prompt `prompt`, um array de URLs de imagens de referência `image_urls` e o modelo `model` para obter o resultado processado, conforme ilustrado:

Aqui configuramos os Headers da Requisição: * `accept`: formato desejado da resposta, aqui definido como `application/json` (formato JSON). * `authorization`: chave de acesso à API, selecionável após a solicitação. No corpo da requisição (Request Body), configuramos: * `model`: modelo para geração do vídeo, suportando `sora-2` (modo padrão) e `sora-2-pro` (modo HD). O `sora-2-pro` suporta vídeos de 25 segundos, enquanto `sora-2` suporta 10 e 15 segundos. * `size`: resolução do vídeo, `small` para padrão e `large` para HD (apenas Versão 1). * `duration`: duração do vídeo, suportando 10, 15 e 25 segundos (25 segundos apenas para `sora-2-pro`, Versão 1). * `orientation`: orientação do vídeo, `landscape` (paisagem) ou `portrait` (retrato) (apenas Versão 1). * `image_urls`: array de URLs de imagens de referência para geração de vídeo a partir de imagens (apenas Versão 1). * `character_url`: link do personagem, vídeos não podem conter pessoas reais (apenas Versão 1). * `character_start`/`character_end`: segundos de início e fim da aparição do personagem, intervalo de 1 a 3 segundos (apenas Versão 1). * `prompt`: prompt de texto (obrigatório). * `callback_url`: URL para callback assíncrono. * `version`: versão da API, `"1.0"` (padrão) ou `"2.0"`. Após configurar, o código correspondente é gerado à direita, conforme a imagem:

Clique em "Try" para testar. O resultado obtido será: ```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" } ] } ``` Campos retornados: * `success`: status da tarefa de geração do vídeo. * `task_id`: ID da tarefa. * `trace_id`: ID de rastreamento da tarefa. * `data`: lista de resultados da tarefa. * `id`: ID do vídeo gerado. * `video_url`: URL do vídeo gerado. * `state`: estado da tarefa. Com isso, basta acessar o link em `data` para obter o vídeo gerado. Também é possível copiar o código gerado para integração, por exemplo, 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" }' ``` ## Tarefa de Geração de Vídeo a partir de Imagem (Versão 1) Para gerar vídeo a partir de imagem, o parâmetro `image_urls` deve conter URLs das imagens de referência, conforme: * `image_urls`: array de URLs das imagens de referência para a tarefa. Não envie imagens reais com rostos humanos para evitar falha na tarefa. Exemplo de preenchimento:

Código gerado automaticamente:

Exemplo em Python: ```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) ``` Ao executar, o resultado será: ``` { "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" } ] } ``` O resultado confirma a geração de vídeo a partir da imagem, semelhante ao exemplo anterior. ## Tarefa de Geração de Vídeo com Personagem (Versão 1) Para gerar vídeo com personagem, o parâmetro `character_url` deve conter o link do vídeo para criação do personagem. O vídeo não pode conter pessoas reais para evitar falha. * `character_url`: link do vídeo para criação do personagem, sem pessoas reais. Exemplo de preenchimento:

Código gerado automaticamente:

Exemplo em Python: ```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) ``` Ao executar, o resultado será: ``` { "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" } ] } ``` O resultado confirma a geração de vídeo com personagem, semelhante ao exemplo anterior. ## Modo Versão 2.0 Além do modo Versão 1.0, a API suporta o modo Versão 2.0, ativado ao definir o parâmetro `version` como `"2.0"`. Este modo suporta vídeos mais curtos e controle de resolução em nível de pixel. ### Parâmetros da Versão 2.0 | Parâmetro | Tipo | Obrigatório | Descrição | | -------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------- | | `version` | string | Sim | Definir como `"2.0"` | | `prompt` | string | Sim | Prompt para geração do vídeo | | `model` | string | Não | `sora-2` (padrão) ou `sora-2-pro` | | `duration` | integer | Não | Duração do vídeo: `4` (padrão), `8`, `12` segundos | | `size` | string | Não | Resolução: `720x1280` (padrão), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | Não | Array de URLs de imagens de referência, usa apenas a primeira, deve ter tamanho compatível com `size` | | `callback_url` | string | Não | URL para callback assíncrono | ### Exemplo Básico ```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" }' ``` Exemplo em Python: ```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) ``` Exemplo em JavaScript: ```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); ``` O formato de resposta é igual ao da Versão 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 de Imagem de Referência (Versão 2.0) No modo Versão 2.0, pode-se passar imagens de referência via `image_urls` (apenas a primeira imagem é usada): ```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**: A dimensão da imagem de referência deve corresponder ao parâmetro `size`. Por exemplo, se `size` for `1280x720`, a imagem deve ter 1280×720 pixels. ### Comparação dos Parâmetros entre Versão 1.0 e 2.0 | Parâmetro | Versão 1.0 | Versão 2.0 | | --------------- | --------------------- | --------------------------------------- | | `version` | 1.0 (padrão) | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 segundos | ✅ 4/8/12 segundos | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ múltiplas imagens | ✅ apenas a primeira | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## Callback Assíncrono Como a geração de vídeos pode levar de 1 a 2 minutos, a API suporta callback assíncrono para evitar conexões HTTP longas que consomem recursos. O fluxo é: o cliente envia a requisição com o campo `callback_url`. A API responde imediatamente com um `task_id`. Quando a tarefa terminar, a API envia um POST JSON para o `callback_url` com o resultado, incluindo o `task_id` para associação. Exemplo de uso: O webhook é um serviço que recebe requisições HTTP. Para demonstração, pode-se usar o site público [https://webhook.site/](https://webhook.site/), que gera uma URL de webhook, como: `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa` Configure o campo `callback_url` com essa URL e preencha os demais parâmetros, conforme a imagem:

Ao executar, o retorno imediato será: ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` Após alguns instantes, no site do webhook será possível visualizar o resultado da geração do vídeo, conforme: ![](https://cdn.xhuoapi.ai/0j7nra.png) Exemplo do conteúdo recebido: ```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" } ] } ``` O campo `task_id` permite correlacionar o resultado com a solicitação inicial. ## Tratamento de Erros Ao chamar a API, erros podem ocorrer e serão retornados códigos e mensagens correspondentes, por exemplo: * `400 token_mismatched`: requisição inválida, parâmetros ausentes ou inválidos. * `400 api_not_implemented`: requisição inválida, parâmetros ausentes ou inválidos. * `401 invalid_token`: não autorizado, token inválido ou ausente. * `429 too_many_requests`: muitas requisições, limite excedido. * `500 api_error`: erro interno do servidor. ### Exemplo de Resposta de Erro ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusão Este documento apresentou como usar a API de Geração de Vídeos Sora para criar vídeos a partir de prompts e imagens de referência. Esperamos que facilite sua integração e uso da API. Em caso de dúvidas, entre em contato com nossa equipe de suporte técnico.