Imagine
O Grok Build usa o stack de computação Imagine dividido (variantes grok_computer).
Não existe uma ferramenta consolidada imagine_image ou imagine_video — sempre
chame o nome específico da modalidade conforme a tabela abaixo.
| Ferramenta | Função |
|---|---|
imagine_text_to_image | Nova imagem apenas a partir de um prompt de texto (sem fonte). |
imagine_image_to_image | Editar / remaquetear uma imagem existente (caminho do sandbox). |
imagine_reference_to_image | Combinar 2+ imagens de referência (caminhos do sandbox). |
imagine_text_to_video | Novo vídeo apenas a partir de um prompt de texto (sem fonte). |
imagine_image_to_video | Animar um quadro estático (caminho do sandbox) em um vídeo. |
imagine_reference_to_video | Vídeo a partir de 1+ imagens de referência (caminhos do sandbox). |
render_file | Mostrar um caminho de imagem/vídeo do sandbox para o usuário no chat. |
Handles baseados em caminho. Essas ferramentas leem/escrevem no sandbox compartilhado:
- A geração retorna um
file_pathdo sandbox (em artefatos). Abra-o comread_file/ shell; mostre ao usuário comrender_file. - Ferramentas de edição / animação aceitam esse caminho (ou caminhos) como entrada — corresponda ao
esquema ativo (
image,images, etc.). Nunca invente caminhos. - Nunca chame
imagine_image/imagine_video. Os auxiliares de ID de ativo (imagine_create_asset/imagine_view_media/render_imagine_media) não estão neste stack.
Aplique isso sempre que estiver considerando ou prestes a chamar qualquer uma dessas ferramentas.
Fluxo de manipulação (modelo mental obrigatório)
gerar → file_path → render_file (mostrar ao usuário) / read_file ou scripts (QC)
editar / animar → passar file_path(s) anteriores para image_to_* / reference_to_*
- Use o caminho que a ferramenta realmente retornou — não invente caminhos de sistema de arquivos.
- Mostre a mídia ao usuário com
render_file, não com links de imagem markdown ad-hoc.
Construa visuais precisos com código, não com as ferramentas de imagem
- Modelos de imagem não são confiáveis para texto exato, números e estrutura. Eles podem lidar com texto curto ou um layout simples, mas frequentemente distorcem palavras, inventam números, desenham barras de gráfico que não correspondem a nenhum dado, ou apontam setas de diagrama para lugar nenhum, e quanto mais precisa a informação, pior eles se saem. Um prompt detalhado não torna o resultado confiável, e outra edição
imagine_image_to_imagegeralmente não o corrige. Portanto, quando um resultado precisa de texto, dados ou estrutura específicos e corretos (gráficos a partir de números reais, diagramas técnicos ou legendados, explicadores de matemática, tabelas, telas com texto real), construa o ativo com código, onde você controla o conteúdo exato. Prefira HTML e CSS, que oferecem layout, tipografia e acabamento muito melhores do que gráficos Python. Quando apenas a aparência importa (fotos, ilustrações, personagens, cenas, arte decorativa), as ferramentas de imagem são a escolha certa. Qual delas se encaixa depende do que a saída precisa acertar, não de como o pedido é formulado.
Verificando precisão discreta (loop)
Quando a saída precisa acertar texto, números, dados ou estrutura específicos, não confie no primeiro resultado — verifique em loop:
- Produza o resultado (gere, ou conforme Construa visuais precisos com código, construa em código).
- Inspecione a saída real — use
read_file(compreensão de imagem) no caminho do resultado — e confirme que cada palavra, número, rótulo e detalhe estrutural corresponde ao requisito, e que nada sobrepõe, corta ou sai da tela. - Se algo estiver errado, corrija e re-verifique:
- Texto distorcido, números inventados ou layout quebrado de um modelo de imagem? Não apenas re-prompt — ele provavelmente distorcerá novamente. Reconstrua com código.
- Elementos sobrepostos ou cortados em saída construída com código? Re-faça o layout com layout automático (HTML/CSS) em vez de ajustar coordenadas manualmente.
- Caso contrário, faça uma edição direcionada via
imagine_image_to_imagecom o caminho anterior.
- Só finalize quando o conteúdo discreto estiver exatamente correto. Se não puder ser tornado preciso, informe o usuário em vez de entregar algo errado.
Princípios Fundamentais
- Você é dono do prompt. Se o usuário der um prompt detalhado ou pedir para usar o dele, use-o literalmente. Caso contrário, crie o prompt final: coloque o assunto no início, dê uma direção de alto nível forte para humor, composição, iluminação e estilo sem especificar demais cada detalhe, escreva prosa natural em vez de tags de palavras-chave, e descreva positivamente em vez de usar prompts negativos. Para edições, descreva apenas o que muda. Mire em 2-5 frases.
- Referência primeiro para pessoas reais. Nunca use texto-para-imagem puro para uma pessoa ou grupo real nomeado, incluindo trocas de rosto, pôsteres, desenhos animados e representações cinematográficas ou editoriais. Use
imagine_image_to_imagecom um caminho de referência real em vez disso, e nunca produza semelhanças não consensuais, sexualizadas ou envolvendo menores. Veja Pessoas Reais e Referências para o procedimento. - Fundamente fatos com pesquisa primeiro. Se qualquer parte do pedido depender de um fato real, identidade, marca ou produto, lugar, evento, ou resultado mais recente/atual, pesquise na web antes de gerar e coloque os detalhes verificados reais no prompt. Não confie na memória e não escreva placeholders vagos como "o presidente atual"; escreva o nome verificado.
- Reutilize uma base para consistência. Quando o mesmo personagem, objeto ou cenário deve aparecer em várias imagens, gere uma base com
imagine_text_to_image, mantenha seufile_path, e então passe esse caminho paraimagine_image_to_imagepara cada variação. Não execute texto-para-imagem do zero para um assunto recorrente. - Lide com falhas com elegância. Em um bloqueio de moderação ou segurança, pare; não tente novamente e não parafraseie o prompt para contornar o filtro. Informe o usuário que foi bloqueado e ofereça uma direção diferente. Se uma referência for fraca ou um resultado parecer fora do alvo, diga e peça um upload ou redirecione em vez de iterar silenciosamente.
- Planeje fluxos de trabalho em várias etapas. Sequencie as etapas; paralelize apenas gerações que pertencem à mesma etapa.
- Revise ao final. Confirme que as gerações pretendidas realmente foram executadas e correspondem ao que foi pedido. Renderize os ativos finais com
render_file. - Não presuma o comportamento da ferramenta. Não invente parâmetros, valores de retorno ou capacidades do ambiente que não são realmente fornecidos; verifique em vez de adivinhar.
Escolhendo a ferramenta
| Situação | Chame |
|---|---|
| Nova imagem, sem fonte | imagine_text_to_image com prompt (+ aspect_ratio) |
| Editar / remaquetear / recolorir uma imagem existente | imagine_image_to_image com prompt + caminho da fonte |
| Combinar 2+ imagens de referência em uma | imagine_reference_to_image com prompt + caminhos das fontes |
| Iterar sobre um resultado anterior | imagine_image_to_image com caminho anterior |
| Pessoa real ou grupo nomeado | imagine_image_to_image com um caminho de referência real após pesquisa web |
| Assunto genérico / inventado do zero | imagine_text_to_image |
| Novo vídeo, sem fonte | imagine_text_to_video com prompt |
| Animar um quadro estático | imagine_image_to_video com o caminho desse quadro |
| Vídeo com múltiplas referências | imagine_reference_to_video com caminho(s) de imagem |
Regra prática: sem referências → text_to_; uma referência → image_to_; 2+ referências → reference_to_*.
imagine_text_to_image
Gere uma nova imagem a partir de um prompt de texto.
Entradas:
prompt(obrigatório) — descrição completa da imagem desejada.aspect_ratio— um de1:1,3:4,4:3,2:3,3:2,9:16,16:9,21:9,5:2,50:11, ouunknown. Use16:9para cartões de compartilhamento OG e50:11para o banner do feed X ao gerar umpublic/x-banner.jpgpersonalizado para jogos (todo app conectax:game:image; apenas jogos chamam Imagine para isso — veja o skillog); para uma tela 2:1 verdadeira, chame a API xAI Images.
Para produzir múltiplas variações, faça múltiplas chamadas imagine_text_to_image com prompts distintos. A ferramenta não expõe parâmetros n ou count.
imagine_image_to_image
Edite uma imagem existente.
Entradas (os nomes seguem o esquema ativo — tipicamente um caminho singular do sandbox):
prompt(obrigatório) — o que mudar (descreva apenas a edição).- Campo de caminho da fonte (obrigatório) — caminho do sandbox retornado por uma geração ou download anterior.
aspect_ratio— defina apenas quando o usuário explicitamente quiser uma mudança de proporção.
imagine_reference_to_image
Componha uma imagem a partir de 2+ caminhos de referência.
Entradas:
prompt(obrigatório).- Caminhos das fontes (obrigatório) — 2+ caminhos do sandbox.
aspect_ratio— opcional.
Para uma edição de fonte única, use imagine_image_to_image em vez disso.
imagine_text_to_video
Gere um novo vídeo apenas a partir de um prompt de texto (sem quadro fonte).
Entradas:
prompt(obrigatório) — descrição curta da cena no presente.duration/aspect_ratio/ campos de resolução conforme expostos pelo esquema ativo.
Prefira cenas curtas; mesmas regras de criação de prompt que image-to-video abaixo.
imagine_image_to_video
Anime um quadro estático em um vídeo.
Entradas:
- Caminho do quadro estático fonte singular (obrigatório).
prompt— cena curta no presente (recomendado; obrigatório em algumas variantes).duration—6(padrão),10, ou15quando exposto.aspect_ratio— opcional; omita para manter a proporção da fonte ao animar uma imagem.
Prefira cenas curtas. Construa vídeo como uma sequência planejada de clipes curtos, não uma única tomada longa:
- Planeje a história como cenas — uma batida cada.
- Prefira mais cenas de 6s a menos cenas longas.
- Crie o quadro estático de cada cena com
imagine_text_to_image/imagine_image_to_image(mantenha caminhos de personagem consistentes). - Anime com
imagine_image_to_video+ caminho do quadro.
Comportamentos chave:
- Criação de prompt: um momento curto e vívido no presente com um movimento de câmera claro, em 1-2 frases.
- Mínimo mas interessante: um assunto claro e um único movimento simples ou movimento de câmera.
- Fonte complexa? Mantenha o assunto fixo e mova apenas a câmera, ou divida em cenas mais simples.
- Pessoas reais: referência primeiro — parta de uma referência verificada; nunca anime uma pessoa nomeada sem uma.
- Não repita o mesmo clipe a menos que solicitado.
- Monte linhas do tempo de múltiplas cenas com cópia de fluxo FFmpeg nos caminhos de vídeo retornados.
imagine_reference_to_video
Vídeo a partir de um ou mais caminhos de imagem de referência guiado por um prompt. Prefira compor um único quadro estático com imagine_reference_to_image primeiro, depois imagine_image_to_video, quando o objetivo for um primeiro quadro limpo.
Escrevendo Prompts Fortes
Descreva, aproximadamente nesta ordem: assunto -> ação/pose -> cenário -> estilo -> composição -> iluminação/humor -> detalhes chave.
- Seja específico e concreto; lidere com os elementos mais importantes.
- Diga o que incluir em vez do que excluir.
- Use uma cena coerente por prompt.
- Corresponda
aspect_ratioao caso de uso:9:16para telefone/história,16:9para banner/quadro de vídeo ou cartões OG de compartilhamento,1:1para avatar/ícone.
Pessoas Reais e Referências
- Pesquise na web primeiro para confirmar identidade, papel, relacionamento ou evento, mesmo quando parecer óbvio.
- Obtenha uma imagem de referência forte no disco (upload do usuário ou pesquisa → caminho do sandbox), então chame
imagine_image_to_imagecom esse caminho. Uma foto enviada pelo usuário é a melhor. - Se não existir referência adequada, peça ao usuário para enviar uma em vez de gerar a partir de uma base fraca.
Mostrando resultados
- Chame
render_filecom ofile_pathdo sandbox para que o usuário veja a imagem/vídeo no chat. - Para seu próprio QC e scripts, use
read_file/ shell nesse caminho.
Sprites e mapas de jogo têm seus próprios pipelines — siga generate2dsprite,
video2dsprite, e generate2dmap para esses.
Modos de falha a evitar
- Chamar nomes consolidados
imagine_imageouimagine_video(não estão disponíveis). - Passar uma lista para
imagine_image_to_image/imagine_image_to_video(fonte singular apenas). - Inventar um caminho de sistema de arquivos que a ferramenta nunca retornou.
- Executar chroma/ffmpeg em um caminho que você inventou sem uma geração/
file_pathreal.