Sora Videos Generation API Integração

Este documento irá apresentar a integração com a API Sora Videos Generation, através da qual é possível inserir parâmetros personalizados para gerar vídeos oficiais da Sora. Esta API suporta dois modos de versão:

Versão 1 (Modo Clássico): suporta duration (10/15/25 segundos), orientation (paisagem/retrato), size (pequeno/grande qualidade), imagens de referência image_urls, URL do ### character_url, entre outros parâmetros.
Versão 2 (Modo Parceiro): suporta seconds (4/8/12 segundos), resolução em pixels size (como 1280x720), imagens de referência input_reference, entre outros parâmetros.

Processo de Solicitação

Para usar a API Sora Videos Generation, primeiro acesse o Painel de Controle Ace Data Cloud para obter seu Token API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar. Após a conclusão, você será redirecionado de volta para a página atual. Um Token API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no painel de controle.

📘 Documentação Completa: Sora Videos Generation API →

Uso Básico (Versão 1)

Primeiro, entenda a forma básica de uso da Versão 1, que consiste em inserir a palavra-chave prompt, um array de links de imagens de referência image_urls e o modelo model, para obter o resultado processado. O conteúdo específico é o seguinte:

Podemos ver que aqui configuramos os Cabeçalhos da Solicitação, incluindo:

accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Além disso, configuramos o Corpo da Solicitação, incluindo:

model: o modelo para gerar o vídeo, suportando sora-2 (modo padrão) e sora-2-pro (modo HD). O sora-2-pro suporta vídeos com duration de 25 segundos, enquanto o sora-2 suporta apenas 10 e 15 segundos.
size: qualidade do vídeo, small para qualidade padrão, large para qualidade HD (apenas Versão 1).
duration: duração do vídeo, suportando 10, 15 e 25 segundos, sendo que 25 segundos é suportado apenas pelo sora-2-pro (apenas Versão 1).
orientation: direção da imagem, suportando landscape (paisagem) e portrait (retrato) (apenas Versão 1).
image_urls: array de links de imagens de referência, usado para gerar vídeo a partir de imagens (apenas Versão 1).
character_url: link do ###, não podendo aparecer pessoas reais no vídeo (apenas Versão 1).
character_start/character_end: segundos de início e fim da aparição do personagem, com uma diferença de intervalo de 1-3 segundos (apenas Versão 1).
prompt: palavra-chave (obrigatório).
callback_url: URL para o resultado da chamada assíncrona.
async: opcional, se definido como true, a interface retorna imediatamente task_id, não sendo necessário fornecer callback_url, e posteriormente, o resultado pode ser obtido através da interface de consulta de tarefas correspondente.
version: versão da API, "1.0" (padrão) ou "2.0".

Após a seleção, podemos ver que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado:

{
  "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://platform.cdn.acedata.cloud/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"
    }
  ]
}

O resultado retornado contém vários campos, descritos a seguir:

success, o estado atual da tarefa de geração de vídeo.
task_id, o ID da tarefa de geração de vídeo atual.
trace_id, o ID de rastreamento da geração de vídeo atual.
data, a lista de resultados da tarefa de geração de vídeo atual.
- id, o ID do vídeo da tarefa de geração de vídeo atual.
- video_url, o link do vídeo da tarefa de geração de vídeo atual.
- state, o estado da tarefa de geração de vídeo atual.

Podemos ver que obtivemos informações satisfatórias sobre o vídeo, e tudo o que precisamos fazer é acessar o link do vídeo gerado no data para obter o vídeo Sora. Além disso, se você quiser gerar o código correspondente para a integração, pode copiá-lo diretamente, como o código CURL abaixo:

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": "gato correndo no rio",
  "model": "sora-2"
}'

Tarefa de Vídeo a Partir de Imagem (Versão 1)

Se você deseja realizar uma tarefa de vídeo a partir de imagem, primeiro o parâmetro image_urls deve conter os links das imagens de referência, permitindo especificar o seguinte conteúdo:

image_urls: array de links de imagens de referência utilizados na tarefa de vídeo a partir de imagem. Atenção: não deve ser enviado imagens reais de pessoas com rostos, pois isso pode resultar em falha na tarefa.

Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

O código correspondente:

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": "gato correndo no rio",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clicando em executar, pode-se notar que um resultado é obtido imediatamente, como abaixo:

{
  "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://platform.cdn.acedata.cloud/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"
    }
  ]
}

Pode-se ver que o efeito gerado é um vídeo gerado a partir de imagens, e o resultado é semelhante ao acima.

Tarefa de geração de vídeo de personagem (Versão 1)

Se você deseja realizar uma tarefa de geração de vídeo de personagem, primeiro o parâmetro character_url deve ser passado com o link do vídeo necessário para criar o personagem, note que o vídeo não pode conter pessoas reais, caso contrário, falhará, você pode especificar o seguinte conteúdo:

character_url: link do vídeo necessário para criar o personagem, note que o vídeo não pode conter pessoas reais, caso contrário, falhará.

Um exemplo de preenchimento é o seguinte:

Após o preenchimento, o código gerado automaticamente é o seguinte:

O código correspondente:

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": "gato correndo no rio",
    "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)

Clicando em executar, pode-se notar que um resultado é obtido imediatamente, como abaixo:

{
  "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://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

Pode-se ver que o efeito gerado é um vídeo de geração de personagem, e o resultado é semelhante ao acima.

Modo Versão 2.0

Além do modo Versão 1.0 mencionado acima, esta API também suporta o modo Versão 2.0, ativando-o ao definir o parâmetro version como "2.0". O modo Versão 2.0 suporta durações de vídeo mais curtas e controle de resolução em nível de pixel.

Descrição dos parâmetros da Versão 2.0

Parâmetro	Tipo	Obrigatório	Descrição
`version`	string	Sim	Definido como `"2.0"`
`prompt`	string	Sim	Palavra-chave para gerar o 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, apenas a primeira imagem é usada, o tamanho da imagem deve ser consistente com o parâmetro `size`
`callback_url`	string	Não	URL de 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": "gato correndo no rio",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'

Código Python correspondente:

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": "gato correndo no rio",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Código JavaScript correspondente:

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: 'gato correndo no rio',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

O formato do resultado retornado é o mesmo 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 Imagens de Referência (Versão 2.0)

No modo Versão 2.0, é possível passar imagens de referência através do parâmetro image_urls para guiar a geração do vídeo (apenas a primeira imagem é utilizada):

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": "uma pessoa caminhando por um lindo jardim",
    "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: As dimensões da imagem de referência devem ser consistentes com o parâmetro size, por exemplo, quando size é 1280x720, as dimensões da imagem de referência devem ser 1280×720.

Comparação de Parâmetros entre Versão 1.0 e Versão 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`	✅ paisagem/retrato	❌
`size`	✅ pequeno/grande	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ várias imagens de referência	✅ apenas a primeira imagem
`character_url`	✅	❌
`callback_url`	✅	✅

Callback Assíncrono

Devido ao tempo relativamente longo para a geração de vídeos pela API Sora, que leva cerca de 1-2 minutos, se a API não responder por um longo período, a requisição HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente faz a solicitação, deve especificar um campo callback_url adicional. Após a solicitação da API, a API retornará imediatamente um resultado, contendo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado do vídeo gerado será enviado para o callback_url especificado pelo cliente, também incluindo o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. Abaixo, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber requisições HTTP, e os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público https://webhook.site/, onde ao abrir o site você obterá uma URL de Webhook, como mostrado na imagem:

Copie esta URL, que pode ser usada como Webhook. O exemplo aqui é https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa. Em seguida, podemos definir o campo callback_url para a URL do Webhook acima, enquanto preenchemos os parâmetros correspondentes, conforme mostrado na imagem:

Ao clicar em executar, você verá que receberá imediatamente um resultado, como abaixo:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

Após alguns instantes, podemos observar o resultado do vídeo gerado em https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, como mostrado na imagem:

O conteúdo é o seguinte:

{
  "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://platform.cdn.acedata.cloud/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"
    }
  ]
}

Podemos ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos mencionados anteriormente, permitindo que a tarefa seja associada pelo ID.

Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:

400 token_mismatched: Requisição inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented: Requisição inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
429 too_many_requests: Muitas requisições, você excedeu o limite de taxa.
500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha ao buscar"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusão

Através deste documento, você já entendeu como usar a API de Geração de Vídeos Sora para gerar vídeos através da entrada de palavras-chave e imagens de referência. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

Sora Videos Generation API Integração

Processo de Solicitação

Uso Básico (Versão 1)

Tarefa de Vídeo a Partir de Imagem (Versão 1)

Tarefa de geração de vídeo de personagem (Versão 1)

Modo Versão 2.0

Descrição dos parâmetros da Versão 2.0

Exemplo básico

Uso de Imagens de Referência (Versão 2.0)

Comparação de Parâmetros entre Versão 1.0 e Versão 2.0

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão

​Processo de Solicitação

​Uso Básico (Versão 1)

​Tarefa de Vídeo a Partir de Imagem (Versão 1)

​Tarefa de geração de vídeo de personagem (Versão 1)

​Modo Versão 2.0

​Descrição dos parâmetros da Versão 2.0

​Exemplo básico

​Uso de Imagens de Referência (Versão 2.0)

​Comparação de Parâmetros entre Versão 1.0 e Versão 2.0

​Callback Assíncrono

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Uso Básico (Versão 1)

Tarefa de Vídeo a Partir de Imagem (Versão 1)

Tarefa de geração de vídeo de personagem (Versão 1)

Modo Versão 2.0

Descrição dos parâmetros da Versão 2.0

Exemplo básico

Uso de Imagens de Referência (Versão 2.0)

Comparação de Parâmetros entre Versão 1.0 e Versão 2.0

Callback Assíncrono

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão