> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Videos Generation API Integração

> Grok API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [Grok Videos Generation API →](https://platform.acedata.cloud/documents/grok-videos)

## Descrição do Modelo

Esta API seleciona o ponto de extremidade superior através do sufixo do nome do modelo: `:reverse` utiliza o ponto de extremidade rápido/padrão (mais barato), `:official` utiliza o ponto de extremidade oficial (qualidade de imagem mais alta, cobrança por segundos de saída). Suporta quatro modelos:

* `grok-imagine-video-1.5-fast:reverse` (padrão): suporta vídeos gerados por texto (apenas `prompt`) e vídeos gerados por imagem (passando `image_url`), com duração de 6–30 segundos, cobrança por duração, o mais barato.
* `grok-imagine-video:reverse`: suporta vídeos gerados por texto e por imagem, com duração de 1–15 segundos, cobrança por segundos de saída.
* `grok-imagine-video:official`: ponto de extremidade oficial, suporta vídeos gerados por texto e por imagem, com duração de 1–15 segundos, cobrança por segundos de saída, qualidade de imagem mais alta.
* `grok-imagine-video-1.5:official`: ponto de extremidade oficial, **apenas suporta vídeos gerados por imagem**, **deve** passar `image_url`, com duração de 1–15 segundos, suporta até `1080p`, cobrança por segundos 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:

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

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:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

O código correspondente em Python é o seguinte:

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

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

## 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:

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## 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`:

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## 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:

```json theme={null}
{
  "prompt": "Uma cena cinematográfica de um gatinho perseguindo uma borboleta em um jardim iluminado pelo sol",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://seu-dominio.com/callback/grok"
}
```

O resultado retornado imediatamente é o seguinte:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## 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](https://platform.acedata.cloud/documents/grok-tasks) (`POST https://api.acedata.cloud/grok/tasks`) para consultar o status e resultado mais recentes da tarefa com base no `task_id`.

## Explicação de cobrança

O método de cobrança deste serviço é determinado pelo `model`:

* `grok-imagine-video-1.5-fast:reverse`: cobrança por duração, independente da resolução — `6–10` segundos, `11–20` segundos, `21–30` segundos correspondem a diferentes faixas de preço.
* `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`: ponto final oficial, cobrança por "segundos de saída", quanto maior a resolução, maior o preço unitário; modelos oficiais serão cobrados mesmo que a revisão de conteúdo falhe.

Os preços unitários específicos estão sujeitos à página de preços. Solicitações falhadas não são cobradas e não 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.