API do Grok Imagine: gere uma imagem com o SDK do Pipe2

Para acessar a API do Grok Imagine pelo Pipe2, execute o Image Generator com model: 'grok-imagine-image'. Envie um prompt de texto, consulte o ID de execução retornado e obtenha a imagem gerada. Este guia usa a API e a autenticação do Pipe2; não demonstra uma chamada direta à API da xAI.

Selecione o Grok explicitamente

O slug do pipeline é image-generator; o identificador do modelo fica dentro de input. Use grok-imagine-image para o modelo padrão ou grok-imagine-image-quality para Grok Imagine Quality. Auto pode escolher outro mecanismo, então fixe o modelo quando precisar usar o Grok.

O exemplo usa o modelo padrão, nenhuma imagem de referência e quality: 'fast': uma configuração válida do Grok com o menor custo para este fluxo. Fast seleciona uma saída de 1K; auto e hd selecionam 2K. No Grok padrão, o preço base por imagem é atualmente igual nos dois tamanhos; fast não oferece um desconto adicional. Imagens de referência aumentam o custo. Antes de processar um conjunto de solicitações, use EstimatePipelineCost com o mesmo slug e os mesmos dados de entrada.

Execute o exemplo do SDK

Instale o pacote com npm install @pipe2-ai/sdk. Salve o código abaixo como grok-image.mjs, defina PIPE2_TOKEN no ambiente com um token de acesso pessoal do Pipe2 e execute node grok-image.mjs. Sua conta precisa ter créditos suficientes. Mantenha o token no servidor.

import { createClient } from '@pipe2-ai/sdk';

const token = process.env.PIPE2_TOKEN;
if (!token) throw new Error('Set PIPE2_TOKEN');
const client = createClient(token);
const input = {
  model: 'grok-imagine-image',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial photograph, no text.',
  quality: 'fast',
  enhance_prompt: false,
};
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

for (let attempt = 0; attempt < 60; attempt++) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (!run) throw new Error('Run not found');
  if (run.status === 'failed' || run.status === 'cancelled') {
    throw new Error(run.error_message ?? run.status);
  }
  if (run.status === 'completed') {
    const url = run.assets?.[0]?.url;
    if (!url) throw new Error('Completed run has no image asset');
    console.log(url);
    process.exit(0);
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Polling timed out; resume with run ID ${run_pipeline.run_id}`);

A solicitação correspondente ao pipeline é:

{
  "pipeline_slug": "image-generator",
  "input": {
    "model": "grok-imagine-image",
    "prompt": "A small red paper boat on a rain-darkened stone step, soft morning light, editorial photograph, no text.",
    "quality": "fast",
    "enhance_prompt": false
  }
}

Veja a documentação do SDK TypeScript para conhecer o cliente usado por este módulo JavaScript e a referência da API para consultar a API pública.

Guarde o ID até a imagem ficar pronta

RunPipeline retorna um ID de execução, não a imagem pronta. GetPipelineRun obtém o status e os arquivos de saída. O exemplo interrompe a consulta em caso de falha ou cancelamento, verifica se uma execução concluída tem um arquivo e imprime a URL da primeira imagem. Ele limita o acompanhamento a 60 verificações com intervalos de três segundos; isso é uma escolha da aplicação, não uma garantia de tempo de geração.

Se o prazo de consulta se esgotar, retome a consulta ao mesmo ID em vez de enviar uma geração duplicada. Guarde o ID assim que a solicitação for aceita. Em produção, trate também os erros de rede e preserve a referência do arquivo onde sua aplicação precisar dela.

Adicione referências apenas quando forem necessárias

Um prompt de texto é suficiente. Ambos os modelos de imagem do Grok aceitam até três reference_images em JPEG ou PNG, com no máximo 20 MB por imagem. Eles não aceitam reference_videos neste pipeline. As proporções disponíveis são 1:1, 16:9, 9:16, 4:3 e 3:4; o exemplo usa o formato quadrado padrão.

enhance_prompt: false impede que uma solicitação baseada apenas em texto tenha o prompt reescrito antes da geração. Descreva o assunto, o cenário, o enquadramento e a luz, e confira o resultado antes de usá-lo. Para planejar melhor a composição, consulte o guia de prompts do Grok Imagine. Ao adicionar referências, explique a contribuição de cada uma e estime novamente o custo da solicitação modificada.