Pular para o conteúdo
Referência de API
Referência de API

Grok Imagine Imagem para vídeo

Anime uma imagem estática em um clipe curto com os modelos de vídeo Grok Imagine da xAI.

Ver Markdown
01

Visão geral

Use o endpoint de imagem para vídeo com um modelo compatível. Use o Task ID retornado para recuperar seu estado, ou forneça callback_url para as entregas documentadas abaixo.

Início rápido

  1. Crie uma Chave de API e defina-a como RUNAPI_API_KEY.
  2. Escolha um modelo compatível e envie uma requisição POST cujo corpo corresponda ao schema desse modelo.
  3. Armazene o ID da tarefa retornado e, em seguida, faça polling até atingir um estado terminal ou trate os callbacks documentados abaixo.

Endpoint

POST /api/v1/grok_imagine/image_to_video
URL base
https://runapi.ai
Versão da API
v1
Autenticação
Authorization: Bearer YOUR_API_TOKEN
02

Modelos suportados

Abra uma página de modelo para ver preços atuais, limites de taxa e detalhes de uso comercial.

03

Esquema de solicitação

Corpo JSON

Os campos e valores permitidos dependem do modelo selecionado. Quando fornecido, callback_url recebe as entregas da Task documentadas abaixo.

grok-imagine-image-to-video11 campos
aspect_ratiostring
Opcional

Proporção de aspecto da saída.

Valores permitidos: 2:3, 3:2, 1:1, 16:9, 9:16
callback_urlstring
Opcional

URL de webhook para entrega de Task em estado terminal.

duration_secondsinteger
Opcional

Duração da saída em segundos.

Intervalo: 6 - 30
enable_safety_checkerboolean
Opcional

Ativar verificações de segurança de conteúdo.

indexinteger
Opcional

Índice de imagem de origem baseado em zero; usado somente com source_task_id.

Intervalo: 0 - 1
modelstring
Obrigatório

Slug do modelo.

motion_stylestring
Opcional

Estilo de movimento do vídeo; spicy requer source_task_id.

Valores permitidos: fun, normal, spicy
output_resolutionstring
Opcional

Resolução de saída.

Valores permitidos: 480p, 720p Padrão: 480p
promptstring
Opcional

Prompt opcional de geração de vídeo.

Limite: 5000
source_image_urlstring
Opcional

URL de imagem de origem pública; forneça esta ou source_task_id, mas não ambas.

source_task_idstring
Opcional

ID de Tarefa anterior de text-to-image do Grok Imagine; forneça este ou source_image_url, mas não ambos.

grok-imagine-video-1.5-fast8 campos
aspect_ratiostring
Opcional

Proporção de aspecto da saída.

Valores permitidos: 1:1, 16:9, 9:16, 3:2, 2:3
callback_urlstring
Opcional

URL de webhook para entrega de Task em estado terminal.

duration_secondsinteger
Opcional

Duração da saída em segundos.

Padrão: 8 Intervalo: 1 - 30
modelstring
Obrigatório

Slug do modelo.

output_resolutionstring
Opcional

Resolução de saída.

Valores permitidos: 480p, 720p Padrão: 480p
promptstring
Opcional

Prompt opcional de geração de vídeo.

Limite: 5000
reference_image_urlsarray
Opcional

URLs de imagens de referência públicas.

source_image_urlstring
Obrigatório

URL de imagem de origem pública.

grok-imagine-video-1.5-preview8 campos
aspect_ratiostring
Opcional

Proporção de aspecto da saída.

Valores permitidos: 1:1, 16:9, 9:16, 3:2, 2:3, auto Padrão: auto
callback_urlstring
Opcional

URL de webhook para entrega de Task em estado terminal.

duration_secondsinteger
Opcional

Duração da saída em segundos.

Padrão: 8 Intervalo: 1 - 15
modelstring
Obrigatório

Slug do modelo.

output_resolutionstring
Opcional

Resolução de saída.

Valores permitidos: 480p, 720p, 1080p Padrão: 480p
promptstring
Opcional

Prompt opcional de geração de vídeo.

Intervalo: 1 - 4096
reference_image_urlsarray
Opcional

URLs adicionais de imagens de referência públicas; a imagem de origem mais as referências podem totalizar sete imagens.

Limite de itens: 6
source_image_urlstring
Obrigatório

URL de imagem de origem pública.

Regras condicionais

Esses requisitos se aplicam quando todas as condições listadas corresponderem.

  1. Quando model = grok-imagine-image-to-video
    Obrigatório
    Não aceito
    reference_image_urls
  2. Quando model = grok-imagine-video-1.5-fast
    Obrigatório
    Não aceito
    source_task_id, index, motion_style, enable_safety_checker
  3. Quando model = grok-imagine-video-1.5-preview
    Obrigatório
    Não aceito
    source_task_id, index, motion_style, enable_safety_checker
04

Criar aceitação

HTTP 202

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Consulta em processamento

HTTP 200

GET /api/v1/grok_imagine/image_to_video/:id

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Consulta concluída

HTTP 200

GET /api/v1/grok_imagine/image_to_video/:id

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
07

Consulta falhou

HTTP 200

GET /api/v1/grok_imagine/image_to_video/:id

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Callback do cliente: concluído

HTTP 200

POST callback_url

Esquema de resposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
09

Callback do cliente: falhou

HTTP 200

POST callback_url

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

Erros

HTTP 401

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Authentication required"
}
11

Erros

HTTP 401

GET /api/v1/grok_imagine/image_to_video/:id

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Authentication required"
}
12

Erros

HTTP 400

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Mensagem de erro legível por humanos.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Resumo de validação legível por humanos.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Mensagens de validação com chaves por campo de requisição público, com um array de strings legíveis por humanos para cada campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Exemplo de resposta

JSON 
{
  "error": "model must be one of: grok-imagine-image-to-video, grok-imagine-video-1.5-fast, grok-imagine-video-1.5-preview"
}
13

Erros

HTTP 402

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Insufficient balance"
}
14

Erros

HTTP 429

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "API key credit limit exceeded"
}
15

Erros

HTTP 409

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

Erros

HTTP 429

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

Erros

HTTP 503

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

Erros

HTTP 504

POST /api/v1/grok_imagine/image_to_video

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "The request timed out"
}
19

Erros

HTTP 404

GET /api/v1/grok_imagine/image_to_video/:id

Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

Exemplos de Código Gerados

Use cURL diretamente ou instale um SDK para a sua linguagem. Cada exemplo submete a requisição validada mostrada nesta referência.

Instalar

Shell 
pip install runapi-grok-imagine
PYTHON 
import os
from runapi.grok_imagine import GrokImagineClient

client = GrokImagineClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.image_to_video.create(
  model="grok-imagine-video-1.5-preview",
  source_image_url="https://cdn.runapi.ai/public/samples/first-frame.jpg",
  prompt="The camera slowly moves forward."
)