> ## Documentation Index > Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt > Use this file to discover all available pages before exploring further. # Modelos oficiais de vídeo Grok > Gere vídeos a partir de texto ou imagens com grok-imagine-video e grok-imagine-video-1.5, ou edite um vídeo com o modelo base. > [!NOTE] > > Esta página cobre os modelos oficiais `grok-imagine-video` e `grok-imagine-video-1.5`. Eles são diferentes de `grok-imagine-1.5-video-ext`; não misture nomes ou parâmetros. > [!WARNING] > > Nunca exponha a API Key no navegador, variáveis públicas, LocalStorage, URL ou logs. Chame a GccAi pelo backend ou BFF. ```bash cURL theme={null} curl --request POST \ --url https://gccai.heqingsong.uk/v1/videos/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Idempotency-Key: 7d0141e4-a19a-4650-a717-dab777b3a330' \ --data '{ "model": "grok-imagine-video", "prompt": "A cinematic aerial shot of a coastal city at sunrise", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9", "nsfw_check": true }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://gccai.heqingsong.uk/v1/videos/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json", Accept: "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ model: "grok-imagine-video", prompt: "Improve motion consistency and apply cinematic color grading", video: { url: "https://cdn.example.com/source-video.mp4" }, }), }); console.log(response.status, await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [{ "status": "submitted", "task_id": "task_01M09Y4Y101HTFFPV2QPW9DQ3W" }] } ``` ```json 400 theme={null} { "error": { "message": "Invalid request parameters", "type": "invalid_request_error", "param": "resolution", "code": "invalid_request_error" } } ``` ## Visão geral Todos os modos usam o mesmo endpoint assíncrono: ```http theme={null} POST https://gccai.heqingsong.uk/v1/videos/generations ``` | Campos enviados | Modo | Modelos | | - | - | - | | Sem `image_urls` nem `video` | Texto para vídeo | Ambos os modelos | | `image_urls` | Imagens de referência para vídeo | Ambos os modelos | | `video` | Edição de vídeo | Somente `grok-imagine-video` | Após enviar, guarde `data[0].task_id` e consulte: ```http theme={null} GET https://gccai.heqingsong.uk/v1/tasks/{task_id} ``` > [!WARNING] > > Não envie `X-GccAi-Response-Version`: ele ativa resposta HTTP `202`. Esta página usa o formato assíncrono HTTP `200` anterior. ## Capacidades | Capacidade | `grok-imagine-video` | `grok-imagine-video-1.5` | | - | :-: | :-: | | Texto para vídeo | ✅ | ✅ | | Uma ou várias imagens de referência | ✅ | ✅ | | Edição de vídeo | ✅ | ❌ | | `480p` | ✅ | ✅ | | `720p` | ✅ | ✅ | | `1080p` | ❌ | ✅ | | Duração: 1–15 segundos | 1–15 | 1–15 | | Prompt | 1–8000 | 1–8000 | ```text theme={null} duration = 8 resolution = 480p aspect_ratio = auto ``` O contrato público não fixa máximo de imagens. Mantenha um array não vazio de URLs válidas na ordem original; não reutilize limites de modelos de imagem. ## Cabeçalhos **Authorization** `string` *required* `Bearer ` **Content-Type** `string` *required* Use sempre `application/json`. **Accept** `string` `application/json` **Idempotency-Key** `string` `Idempotency-Key` é opcional e muito recomendado para solicitações pagas. Aceita 1–191 caracteres ASCII visíveis; UUID recomendado. Um retry reutiliza chave e body originais. Não troque a chave se o resultado for incerto. Use uma nova chave por operação lógica. Uma repetição deve reutilizar a chave e o corpo originais. ## Parâmetros ### Campos comuns **model** `string` *required* Nome oficial; edição apenas com o modelo base * `grok-imagine-video` * `grok-imagine-video-1.5` **prompt** `string` *required* Instrução não vazia, máximo 8000 Unicode `Array.from(prompt).length` **nsfw\_check** `boolean` (default: false) Define se a moderação de conteúdo será executada antes do envio da tarefa de vídeo. * `true`: Usa `omni-moderation-latest` para revisar o prompt e as imagens de entrada * `false` ou omitido: Não solicita moderação nem adiciona custo ou latência de revisão (padrão) ### Campos de geração **duration** `integer` (default: 8) Somente geração; inteiro 1–15, padrão 8 **resolution** `string` (default: 480p) Base: `480p/720p`; 1.5: `480p/720p/1080p`; padrão `480p` * `grok-imagine-video`: `480p`, `720p` * `grok-imagine-video-1.5`: `480p`, `720p`, `1080p` **aspect\_ratio** `string` (default: auto) Somente geração; `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2` ou `2:3` * `auto` * `1:1`, `16:9`, `9:16` * `4:3`, `3:4`, `3:2`, `2:3` **image\_urls** `string[]` Array opcional; cada item é uma URL HTTPS pública; omitir se vazio * Cada item deve ser uma URL HTTPS pública; URL relativa, Data URL e Base64 puro não são aceitos. * Não envie aliases como `image`, `images` ou `input_reference`. * A ordem é preservada; URLs repetidas ocupam várias entradas e podem ser cobradas mais de uma vez. ### Campos de edição de vídeo **video** `object` Vídeo fonte `{url}` em HTTPS público; somente Base **URL** **url** `string` *required* HTTPS A edição requer `model`, `prompt` e `video`, com `nsfw_check` opcional. Não envie `duration`, `resolution`, `aspect_ratio` nem `image_urls`; a plataforma detecta a duração da origem. ## Tipos de solicitação TypeScript Use uma união discriminada para impedir campos de geração na edição. ```ts theme={null} type GrokVideoModel = | "grok-imagine-video" | "grok-imagine-video-1.5"; type GrokVideoResolution = "480p" | "720p" | "1080p"; type GrokVideoAspectRatio = | "auto" | "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3"; interface GrokVideoGenerateRequest { model: GrokVideoModel; prompt: string; nsfw_check?: boolean; duration?: number; resolution?: GrokVideoResolution; aspect_ratio?: GrokVideoAspectRatio; image_urls?: string[]; } interface GrokVideoEditRequest { model: "grok-imagine-video"; prompt: string; nsfw_check?: boolean; video: { url: string }; } type GrokVideoRequest = | GrokVideoGenerateRequest | GrokVideoEditRequest; ``` ## Exemplos **Texto para vídeo** ```json theme={null} {"model":"grok-imagine-video","prompt":"A cinematic aerial shot at sunrise","duration":5,"resolution":"720p","aspect_ratio":"16:9"} ``` **1.5 · 1080p** ```json theme={null} {"model":"grok-imagine-video-1.5","prompt":"A smooth studio product commercial","duration":5,"resolution":"1080p","aspect_ratio":"16:9"} ``` **Uma ou várias imagens de referência** ```json theme={null} { "model":"grok-imagine-video-1.5", "prompt":"Use the first image as subject and the second as style", "duration":5, "resolution":"720p", "aspect_ratio":"16:9", "image_urls":[ "https://cdn.example.com/subject.jpg", "https://cdn.example.com/style.jpg" ] } ``` **Edição de vídeo** ```json theme={null} { "model":"grok-imagine-video", "prompt":"Improve motion consistency and apply cinematic color grading", "video":{"url":"https://cdn.example.com/source.mp4"} } ``` ## Tarefas assíncronas ### Criação bem-sucedida Uma criação bem-sucedida retorna HTTP `200`. Salve `data[0].task_id`; o envio não significa vídeo concluído. Um ID de tarefa significa enviado, não concluído. ```json theme={null} { "code":200, "data":[{"status":"submitted","task_id":"task_01M09Y4Y101HTFFPV2QPW9DQ3W"}] } ``` ### Consultar tarefa ```http theme={null} GET https://gccai.heqingsong.uk/v1/tasks/{task_id} Authorization: Bearer Accept: application/json ``` Consulte `GET /v1/tasks/{task_id}` a cada 3–5 segundos. Após recarregar, retome com o ID salvo. | `data.status` | Significado | Ação | | - | - | - | | `pending` | Na fila | Continuar consultando | | `processing` | Gerando | Mostrar progresso | | `completed` | Concluída | Ler resultado e parar | | `failed` | Falhou e foi reembolsada | Mostrar erro e parar | | `unknown` | Temporariamente desconhecida | Reduzir frequência e tentar depois | ### Resposta concluída ```json theme={null} { "code":200, "data":{ "id":"task_xxx", "status":"completed", "progress":100, "created":1787040038, "completed":1787040081, "actual_time":43, "estimated_time":100, "cost":0.072, "credits_cost":0.72, "result":{"videos":[{"url":["https://cdn.example.com/result.mp4"],"expires_at":1787126481}]} } } ``` `result.videos[0].url` é um array de strings, não uma string. Valide cada valor como URL HTTPS. Recomenda-se validação em tempo de execução: ```ts theme={null} function extractVideoURLs(payload: unknown): string[] { const groups = (payload as any)?.data?.result?.videos; if (!Array.isArray(groups)) return []; return groups.flatMap((group: any) => Array.isArray(group?.url) ? group.url.filter( (url: unknown): url is string => typeof url === "string" && /^https:///i.test(url), ) : [], ); } ``` Use `expires_at` para expiração. Não fixe duração; peça download ou armazenamento. ### Resposta com falha ```json theme={null} { "code":200, "data":{ "id":"task_xxx", "status":"failed", "progress":100, "cost":0, "credits_cost":0, "error":{"message":"Task failed.","type":"task_failed","param":"","code":"task_failed"} } } ``` > [!WARNING] > > A consulta pode retornar HTTP `200` com `data.status=failed`. Decida por `data.status`; tarefa falha tem `cost=0`. ## Catálogo de preços ```http theme={null} GET https://gccai.heqingsong.uk/api/pricing/models/all ``` Leia `GET /api/pricing/models/all` e encontre o `id` em `data.models.video`. Preços são estimativas; o valor final é `data.cost`. ### Preço do vídeo de saída ```json theme={null} { "fixed_prices":{ "unit":"usd_per_second", "dimension":"resolution", "items":[ {"key":"480P","original_price":0.05,"after_discount":0.04}, {"key":"720P","original_price":0.07,"after_discount":0.056} ] } } ``` * As chaves de preço são `480P/720P/1080P`, e a solicitação usa minúsculas; normalize ao consultar. * `default` é metadado de compatibilidade, não uma resolução selecionável. * Use `after_discount` diretamente; não aplique o desconto novamente. ### Preço do material de entrada ```json theme={null} {"unit":"usd_per_image","original_price":0.002,"after_discount":0.0016} ``` ```json theme={null} {"unit":"usd_per_second","original_price":0.01,"after_discount":0.008} ``` O preço de vídeo é um objeto escalar. Não exija `items`, `billing_mode` ou `max_billable_seconds`. O modelo 1.5 não tem preço de entrada de vídeo. ### Fórmulas de estimativa ```text theme={null} Geração = preço de saída/segundo × duração + preço por imagem × quantidade Edição = preço 720P/segundo × segundos fonte + preço de entrada × segundos fonte ``` Preços específicos e arredondamento podem alterar a estimativa. O valor final é sempre `data.cost`. ## Regras do frontend ### Troca de modelo * Base mostra `480p/720p`; 1.5 também `1080p`. * Ao trocar de 1.5 `1080p` para Base, voltar a `480p`. * Edição fixa `grok-imagine-video`. ### Troca de modo | Modo | Controles visíveis | Campos enviados | Deve limpar | | - | - | - | - | | Geração | `prompt/duration/resolution/aspect_ratio/nsfw_check` | Campos de geração | `image_urls/video` | | Imagens de referência | Campos de geração + `image_urls` | Campos de geração + `image_urls` | `video` | | Edição de vídeo | `prompt/video/nsfw_check` | `model/prompt/video/nsfw_check` | `duration/resolution/aspect_ratio/image_urls` | `nsfw_check` é opcional em todos os modos. Envie `true` com a moderação ativa; omita ou envie `false` quando desativada. Desative o botão quando alguma condição for verdadeira: * Texto omite `image_urls` e `video`. * Referência envia `image_urls` e omite `video`. * Edição limpa campos de geração. * Desative com prompt, duração, resolução ou URL inválida, upload ativo ou envio duplicado. * Prompt ≤8000 Unicode e duração inteira 1–15. * Somente URL HTTPS pública; omitir `image_urls` vazio. ## Erros comuns | HTTP / Status | Causa | Tratamento | | - | - | - | | `400` | Parâmetro, prompt ou enum inválido | Mostrar mensagem e campo | | `401` | Chave ausente ou inválida | Não repetir; verificar servidor | | `402` | Saldo insuficiente | Solicitar recarga | | `403` | Sem permissão | Não repetir automaticamente | | `409` | Conflito idempotente ou solicitação ativa | Manter chave e tentar depois | | `429` | Limite | Respeitar `Retry-After` | | `500/502/503` | Falha temporária | Retries limitados com chave original | | `failed` | Tarefa assíncrona falhou | Parar consulta; custo zero | ## Checklist * API Key apenas em backend ou BFF. * Não misturar modelos oficiais com `grok-imagine-1.5-video-ext`. * Prompt ≤8000 Unicode e duração inteira 1–15. * Somente URL HTTPS pública; omitir `image_urls` vazio. * Na edição, envie apenas `model/prompt/video` mais `nsfw_check` opcional e use o modelo Base. * Ler `data[0].task_id` e final em `data.status`. * Ler `result.videos[].url[]` e respeitar `expires_at`. * Exibir catálogo e usar `data.cost` final. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.