Saltar para o conteúdo principal
Este documento apresentará a integração da Grok Videos Generation API, que pode gerar vídeos Grok Imagine (xAI) através da entrada de texto, imagens e imagens de referência opcionais.

Processo de Solicitação

Para usar a Grok Videos Generation API, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado. 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 esta página. Um Token de 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 experimentar; quando o crédito acabar, você pode recarregar o saldo geral no painel de controle.
📘 Documentação completa: Grok Videos Generation API →

Descrição dos modelos

Os quatro modelos públicos a seguir podem ser selecionados por meio de model. As capacidades e formas de cobrança específicas são as seguintes:
  • grok-imagine-video-1.5-fast:reverse (padrão): oferece suporte a texto para vídeo (transmita apenas prompt) e imagem para vídeo (transmita image_url), com duração de 6 a 30 segundos, cobrança por faixas de duração e o menor preço.
  • grok-imagine-video:reverse: oferece suporte a texto para vídeo e imagem para vídeo, com duração de 1 a 15 segundos e cobrança por segundo de saída.
  • grok-imagine-video:official: oferece suporte a texto para vídeo e imagem para vídeo, com duração de 1 a 15 segundos, cobrança por segundo de saída e maior qualidade de imagem.
  • grok-imagine-video-1.5:official: oferece suporte apenas a imagem para vídeo; é obrigatório transmitir image_url. A duração é de 1 a 15 segundos, com suporte a até 1080p e cobrança por segundo de saída.

Uso Básico

Primeiro, entenda a forma básica de uso, passando os parâmetros de texto prompt, modelo model, etc., para gerar o vídeo correspondente. Aqui, configuramos os Cabeçalhos da Solicitação, incluindo:
  • accept: o formato de resposta desejado, aqui 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:
  • prompt: texto que descreve o conteúdo do vídeo a ser gerado. Obrigatório ao fazer vídeos gerados por texto; opcional ao passar image_url.
  • model: modelo para gerar o vídeo, podendo ser grok-imagine-video-1.5-fast:reverse (padrão), grok-imagine-video:reverse, grok-imagine-video:official ou grok-imagine-video-1.5:official.
  • image_url: link da imagem de entrada para vídeos gerados por imagem. Obrigatório quando model é grok-imagine-video-1.5:official.
  • reference_image_urls: array de links de imagens de referência opcionais, usadas para guiar o estilo ou conteúdo do vídeo.
  • aspect_ratio: proporção largura-altura do vídeo gerado, podendo ser 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
  • resolution: resolução de saída, podendo ser 480p (padrão), 720p ou 1080p.
  • duration: duração do vídeo gerado (segundos). grok-imagine-video-1.5-fast:reverse tem intervalo de 6–30, os outros modelos têm intervalo de 1–15, padrão 6. Recomenda-se usar 6 segundos ou 10 segundos, essas duas durações padrão são relativamente estáveis.
  • callback_url: endereço de callback assíncrono, após a configuração, a API retornará imediatamente task_id, e quando a tarefa for concluída, o resultado será enviado para esse endereço.
  • async: opcional, se definido como true, a interface retornará imediatamente task_id, sem necessidade de fornecer callback_url, e posteriormente, você pode consultar a interface de consulta de tarefas correspondente para obter o resultado.
Clique no botão “Try” para testar, e o resultado obtido será semelhante ao seguinte:
O resultado retornado contém vários campos, descritos a seguir:
  • success: se a solicitação de geração de vídeo foi bem-sucedida.
  • task_id: ID da tarefa de geração de vídeo.
  • trace_id: ID de rastreamento da solicitação, usado para solucionar problemas.
  • data: lista de resultados do vídeo gerado.
    • id: identificador único do vídeo gerado.
    • video_url: endereço do link do vídeo gerado.
    • state: estado da tarefa de geração de vídeo, podendo ser pending / succeeded / failed.
Precisamos apenas obter o vídeo gerado através do link video_url no resultado data. O código correspondente em CURL é o seguinte:
O código correspondente em Python é o seguinte:

Vídeos Gerados por Imagem

Se você deseja gerar um vídeo com base em uma imagem de entrada, pode passar image_url. Ao usar grok-imagine-video-1.5:official, este campo deve ser fornecido:

Direção por Imagens de Referência

Se você deseja usar uma ou mais imagens de referência para guiar o estilo ou conteúdo do vídeo gerado, pode passar um array de links de imagens em reference_image_urls:

Callback Assíncrono

A geração de vídeo requer um certo tempo de processamento. Se não desejar manter uma conexão longa aguardando, pode passar callback_url, nesse caso a API retornará imediatamente task_id, e após a conclusão da tarefa, enviará o resultado final para esse endereço:
O resultado retornado imediatamente é o seguinte:

Consultar resultado da tarefa

Se você usou um callback assíncrono ou deseja consultar ativamente o status da tarefa, pode usar a Grok Tasks API (POST https://api.acedata.cloud/grok/tasks) para consultar o status e resultado mais recentes da tarefa com base no task_id.

Informações sobre cobrança

A forma de cobrança deste serviço é determinada por model:
  • grok-imagine-video-1.5-fast:reverse: cobrança por faixas de duração, independentemente da resolução — 6–10 segundos, 11–20 segundos e 21–30 segundos correspondem, respectivamente, a faixas de preço diferentes.
  • grok-imagine-video:reverse: cobrança por «segundos de saída»; preço total = preço unitário × duration.
  • grok-imagine-video:official e grok-imagine-video-1.5:official: cobrança por «segundos de saída»; quanto maior a resolução, maior o preço unitário. Os modelos oficiais são cobrados mesmo que a moderação de conteúdo falhe.
Consulte a página de preços para os valores unitários específicos. Solicitações com falha não são cobradas nem consomem a cota gratuita.

Tratamento de erros

Quando há problemas com a solicitação, a API retornará o código de erro correspondente e a descrição, os mais comuns são:
  • 400: parâmetros da solicitação estão incorretos, por exemplo, vídeo gerado por texto sem prompt, ou grok-imagine-video-1.5:official sem image_url, ou duration fora do intervalo (para grok-imagine-video-1.5-fast:reverse é 6–30, para os outros modelos é 1–15).
  • 401: falha de autenticação, token inválido ou não correspondente à API.
  • 403: saldo insuficiente, ou a palavra-chave foi rejeitada na revisão de conteúdo.
  • 429: solicitações muito frequentes, por favor, tente novamente mais tarde.
  • 500: falha na geração do vídeo ou anomalia no serviço.