Saltar para o conteúdo principal
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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.acedata.cloud/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.