Saltar para o conteúdo principal

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.

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. Após acessar, clique no botão “Acquire”, conforme mostrado: 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á: 
{
  "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: 
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: 
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: 
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âmetroTipoObrigatórioDescrição
versionstringSimDefinir como "2.0"
promptstringSimPrompt para geração do vídeo
modelstringNãosora-2 (padrão) ou sora-2-pro
durationintegerNãoDuração do vídeo: 4 (padrão), 8, 12 segundos
sizestringNãoResolução: 720x1280 (padrão), 1280x720, 1024x1792, 1792x1024
image_urlsarrayNãoArray de URLs de imagens de referência, usa apenas a primeira, deve ter tamanho compatível com size
callback_urlstringNãoURL para callback assíncrono

​
Exemplo Básico

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: 
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: 
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: 
{
  "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): 
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âmetroVersão 1.0Versão 2.0
version1.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/, 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: Exemplo do conteúdo recebido: 
{
    "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

{
  "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.