Como Configurar a Geração de Imagens em Massa com a OpenArt CLI

Antes de programar qualquer coisa

Este tutorial presume que o binário está instalado e autenticado. Se não estiver, instale-o com um único comando e faça login pelo navegador.

curl -fsSL https://raw.githubusercontent.com/OpenArt-AI/cli/main/install.sh | sh
openart login

Confirme a conta, o plano e o saldo de créditos antes de enfileirar um lote que gasta créditos reais.

openart account

Para as etapas de instalação no Windows, fixar uma versão específica ou a referência completa dos comandos, consulte o Repositório da CLI no GitHub em vez de repetir a configuração aqui.

Verifique a adequação e o custo do modelo antes de gastar qualquer coisa

Escolha um modelo que suporte geração de texto para imagem antes de montar o loop de lote. A disponibilidade e os recursos dos modelos podem mudar conforme a OpenArt adiciona novas opções, então evite confiar em um nome que você lembra ou em um padrão implícito.

openart model list

Revise os modelos disponíveis, confirme o suporte a texto-para-imagem e copie o ID do modelo que você quer usar. Guarde o ID em uma variável para reduzir erros de edição nos comandos seguintes.

Se você precisar confirmar exatamente quais parâmetros um modelo aceita antes de adicioná-los a um lote, como campos de largura, altura ou estilo, verifique o formulário dele.

openart model form "$MODEL_ID" text2image

MODEL_ID="<model-id>"

Verifique o preço por imagem do modelo antes de enviar qualquer trabalho.

openart model cost \
  --model "$MODEL_ID" \
  --mode text2image

O model cost o comando retorna apenas uma cotação. Ele não gera uma imagem nem gasta créditos. Execute-o sem flags para listar o preço de cada modelo, do mais barato ao mais caro, ou limite a um modelo e modo como mostrado acima. Multiplique o custo cotado por imagem pelo número de imagens planejadas para estimar o custo do lote. Se seu CSV atribui modelos diferentes a linhas diferentes, solicite uma cotação para cada modelo e calcule cada grupo separadamente.

Visualize a requisição exata com --dry-run

Execute um prompt representativo com o mesmo modelo e as mesmas flags planejadas para o lote.

MODEL_ID="your-model-id"
openart generate image \
  "A red bicycle leaning against a brick wall at sunset" \
  --model "$MODEL_ID" \
  --json \
  --async \
  --dry-run

O comando imprime a requisição que a OpenArt enviaria, incluindo o prompt, o modelo e os parâmetros de geração. A OpenArt não envia um job nem gasta créditos durante um dry run.

A cotação de custo estima o preço de cada imagem. O dry run verifica a própria requisição. Adicione a este comando quaisquer parâmetros pretendidos para o lote, inspecione a saída e corrija padrões inesperados ou problemas de aspas antes de ler o arquivo de prompts real.

Formate a lista de prompts

Usar prompts.txt quando todos os jobs compartilham o mesmo modelo e parâmetros. Armazene um prompt completo por linha.

A watercolor cabin beside a frozen lake
A studio photo of a red ceramic teapot
An isometric library with warm lighting

Mantenha cada prompt em uma única linha física. Um posterior read -r o loop preserva barras invertidas, e usar aspas em "$prompt" passa espaços e aspas como parte do prompt. Pule linhas em branco, a menos que você pretenda enviar um prompt vazio.

Usar prompts.csv quando as linhas precisam de modelos ou dimensões diferentes.

prompt,model,width,height
"A cabin beside a lake","model-id-a",1024,1024
"A teapot, red ceramic","model-id-b",768,1024
"A sign reading ""OPEN""","model-id-a",1024,768

Campos de CSV que contêm vírgulas precisam usar aspas duplas. Represente uma aspa dentro de um campo entre aspas com duas aspas. Um loop de shell baseado em IFS=, não consegue interpretar esses casos corretamente, então a variante CSV deve usar um parser que reconheça CSV, como o do Python csv módulo. Mantenha os nomes dos cabeçalhos estáveis, porque o script posterior os lê diretamente.

Envie o lote com um loop while-read

Salve o script a seguir como submit.sh. Ele lê um prompt por linha, envia cada geração e adiciona todos os IDs de trabalho retornados a job-ids.txt.

#!/usr/bin/env bash
set -uo pipefail
MODEL_ID="replace-with-model-id"
PROMPT_FILE="${1:-prompts.txt}"
JOB_FILE="${2:-job-ids.txt}"
printf '' > "$JOB_FILE"
while IFS= read -r prompt || [[ -n "$prompt" ]]; do
  [[ -z "$prompt" ]] && continue
  if ! response=$(openart generate image "$prompt" \
    --model "$MODEL_ID" \
    --json \
    --async); then
    printf 'Submission failed for prompt %s\n' "$prompt" >&2
    continue
  fi
  if ! job_id=$(jq -er '.id' <<&2
    continue
  fi
  printf '%s\n' "$job_id" >> "$JOB_FILE"
  printf 'Submitted %s\n' "$job_id" >&2
done &2

Substituir replace-with-model-id, torne o script executável e passe um arquivo de prompt diferente se necessário.

chmod +x submit.sh
./submit.sh prompts.txt

O script requer jq para extrair o ID de cada resposta JSON. Se a CLI instalada retornar o identificador em um campo diferente, inspecione uma resposta e ajuste o .id expressão.

O --json flag mantém a saída padrão legível por máquina. O OpenArt envia mensagens de progresso e paginação para a saída de erro padrão, então a substituição de comando captura apenas o JSON que jq precisa. Sem --json, uma saída legível por humanos poderia entrar na response variável e fazer a análise do ID falhar.

O --async faz cada comando retornar assim que o OpenArt aceita o job. Sem ela, o loop espera uma imagem antes de enviar a próxima e pode aguardar até o tempo limite padrão de cinco minutos para cada prompt. O envio assíncrono permite que o loop enfileire o lote completo primeiro.

Cada envio bem-sucedido adiciona um identificador a job-ids.txt.

job_abc123
job_def456
job_ghi789

O loop de coleta pode consumir esse arquivo diretamente. Envios com falha produzem um erro na saída de erro padrão e não adicionam uma entrada inválida ao arquivo.

Execute a variante CSV

O loop CSV divide cada linha em campos e passa o modelo da linha para o comando de geração.

#!/usr/bin/env bash
> job-ids.txt
tail -n +2 prompts.csv |
while IFS=, read -r prompt model
do
  model=${model%$'\r'}
  [ -z "$prompt" ] && continue
  response=$(
    openart generate image "$prompt" \
      --model "$model" \
      --json \
      --async
  ) || continue
  printf '%s\n' "$response" |
    jq -r '.id' >> job-ids.txt
done

Comparado com o loop de texto simples, IFS=, read -r prompt model divide cada linha, e --model "$model" substitui o ID de modelo fixo. O tail o comando pula uma linha de cabeçalho como prompt,model.

A divisão de campos do bash não implementa todas as regras de aspas do CSV. Se os prompts contiverem vírgulas ou aspas escapadas, faça o parse do arquivo com o do Python csv módulo ou outra ferramenta compatível com CSV antes de passar os campos para o comando do OpenArt.

Colete os resultados assim que tudo estiver enviado

Usar openart creation wait quando o script só pode terminar depois que todos os jobs enviados chegarem a um estado terminal. O loop salva cada registro de criação concluída como JSON e registra qualquer job que retorne um erro.

mkdir -p results
: > failed_job_ids.txt
while IFS= read -r job_id; do
  [ -z "$job_id" ] && continue
  if openart creation wait "$job_id" --json \
    > "results/${job_id}.json"; then
    printf 'Completed %s\n' "$job_id"
  else
    printf '%s\n' "$job_id" >> failed_job_ids.txt
    printf 'Failed %s\n' "$job_id" >&2
  fi
done < job_ids.txt

Cada arquivo JSON contém os dados finais da criação, incluindo as informações do asset retornado. Sua próxima etapa de processamento pode ler esses arquivos e baixar ou mover as imagens geradas conforme necessário.

Usar openart creation get quando você quiser uma verificação de status sem bloqueio. Uma verificação manual ou um job de polling agendado pode rodar o mesmo loop mudando apenas um comando.

mkdir -p status
while IFS= read -r job_id; do
  [ -z "$job_id" ] && continue
  openart creation get "$job_id" --json \
    > "status/${job_id}.json"
done < job_ids.txt

O wait o loop pausa em cada ID, mas não torna a geração de imagens serial. Cada job começou após o envio assíncrono anterior, então os jobs posteriores continuam rodando enquanto o loop espera pelo primeiro. Em CI, wait fornece um ponto claro de conclusão. Para monitoramento manual, get permite inspecionar os estados atuais e retornar imediatamente.

O que mais a OpenArt CLI pode fazer

Este tutorial foca em um fluxo de trabalho: transformar uma lista de prompts de texto em um lote de imagens. A CLI abrange muito mais que isso, e vale a pena conhecer o que ela oferece antes de criar ferramentas separadas para isso.

Ele também pode alterar uma imagem que você já tem. Aponte para uma foto no seu computador ou um link, descreva a edição e receba uma nova versão de volta, em vez de gerar apenas do zero. No lado do vídeo, ele cria um vídeo a partir de uma descrição ou dá vida a uma foto estática, com a duração, o formato e a resolução sob seu controle sempre que o modelo escolhido permitir.

Além da geração, a CLI mantém você organizado: alterne entre projetos e workspaces e faça upload de uma imagem de referência uma vez para reutilizá-la em prompts futuros, em vez de reenviar o mesmo arquivo toda vez. Cada resultado pode ser mantido como um link compartilhável ou baixado direto em uma pasta, e você pode revisar tudo o que criou, verificar um job em andamento ou esperar um terminar.

None of that changes the batch pattern in this tutorial. It just means the same terminal-first approach extends past plain text-to-image jobs. See OpenArt's Visão geral da CLI para os comandos por trás de cada um destes.

Onde esse fluxo de trabalho em lote é realmente usado

Alguns casos concretos explicam por que as equipes optam por um lote programado em vez do app web.

Variantes de catálogo de produtos. Uma equipe de e-commerce com uma planilha de 500 SKUs gera uma imagem do produto por linha, alimentando descrições de produtos pela variante CSV, com o modelo e as dimensões de cada linha ajustados ao local onde a imagem vai aparecer (quadrada para uma grade de produtos, retrato para um anúncio de story).

Muros de assets de conteúdo. Uma equipe de conteúdo ou crescimento precisa de 50 variações de thumbnail para um teste A/B antes do almoço. Uma lista de prompts em arquivo de texto e o loop while-read enviam todos os 50 no tempo que leva para escrever os prompts, em vez de clicar 50 vezes no app web.

Conjuntos criativos localizados. Uma equipe de marketing transforma o mesmo conceito base em um conjunto de criativo de anúncio variantes ao longo de uma dúzia de prompts, cada um com uma configuração, modelo ou proporção diferente para um mercado ou canal específico, usando a variante CSV para variar esses campos por linha.

pipelines de CI e de agentes. Um job noturno regenera um conjunto fixo de imagens de prévia sempre que os dados de origem mudam, ou um agente que já executa comandos de shell envia gerações como parte de um fluxo maior de chamada de ferramentas — o mesmo padrão por trás de gerando anúncios de produtos a partir do Claude. Ambos precisam de --json saída e códigos de saída não interativos, não uma sessão de navegador.

Quando optar pelo fluxo de trabalho em lote da CLI em vez do app web ou do MCP

Use o fluxo de lote da CLI quando um script precisa enviar jobs repetíveis, preservar IDs de jobs e coletar resultados sem entrada manual. Ele se encaixa em execuções agendadas de CI, pipelines de shell, processamento de prompts em massa e chamadas de ferramentas de agentes que executam comandos de terminal.

Usar OpenArt para sessões criativas pontuais em que você quer ajustar prompts e configurações enquanto revisa cada resultado. A OpenArt MCP encaixa a geração por conversa dentro de agentes como Claude ou ChatGPT, onde a conversa controla a requisição em vez de um script de shell.

If the goal is not just generating images but also routing each result somewhere else automatically, such as posting a finished image to Telegram, Slack, or Discord, that behavior belongs to an agent, not to this batch script. An agent framework that already supports tool calling can call OpenArt MCP to generate the image, then call a separate messaging tool to deliver it. The while-read loop in this tutorial submits jobs and writes results to disk. It does not send anything anywhere, so a delivery step still needs its own script or agent on top of it.

Escolha a interface que combina com o seu jeito de trabalhar. O repositório da CLI no GitHub cobre a instalação e a referência completa de comandos. A visão geral do MCP acima cobre a geração via chat, se isso se encaixar melhor no seu fluxo do que o processamento em lote baseado em arquivos.

Perguntas frequentes

O que acontece se um job falhar no meio do lote?

Um job com falha não cancela os jobs já enviados. Seu loop de coleta deve registrar o ID do job com falha e continuar, a menos que o script encerre em caso de erros. Inspecione o job com falha usando openart creation get <job-id>.

Como defino um timeout maior sem --async?

O --timeout <seconds> opção estende quanto tempo um comando de geração síncrona aguarda. Por exemplo, adicione --timeout 900 aguardar até 15 minutos. Confirme o valor suportado com openart generate image --help.

Posso usar --async com -o ou --output?

O envio assíncrono retorna um ID de trabalho antes de a imagem existir, então o comando generate não consegue salvar a imagem finalizada imediatamente. Em vez disso, armazene o ID do trabalho durante o envio. Use openart creation wait <job-id> depois para coletar o resultado e tratar sua saída.

Como executo novamente apenas os prompts que falharam?

Uma reexecução exige um registro que mapeie cada prompt ao ID do job enviado. Durante a coleta, grave os IDs com falha e seus prompts em um arquivo separado. Alimente esse arquivo de volta no loop de envio depois de corrigir prompts ou parâmetros inválidos.

Enviar centenas de jobs de uma vez vai atingir um limite de taxa?

O loop como está envia tão rápido quanto o shell consegue iterar, o que pode ultrapassar o limite de taxa em um lote grande. Adicione um breve sleep 0.5 dentro do loop após cada envio, ou controle um contador e pause por alguns segundos a cada 20 a 50 prompts, para manter a taxa de requisições estável em vez de disparar tudo de uma vez.

O --dry-run funciona junto com o --async?

Sim. Combiná-los mostra a requisição exata de um trabalho que, de outra forma, rodaria de forma assíncrona, sem enviá-lo nem gastar créditos. Mantenha ambas as flags no comando de teste enquanto testa e, depois, remova apenas --dry-run quando você passar para o lote real.

Como faço para saber qual imagem veio de qual prompt?

Os IDs de job sozinhos não carregam o texto original do prompt. Grave o prompt e seu ID de job na mesma linha de um arquivo de log no momento do envio, por exemplo printf '%s\t%s\n' "$job_id" "$prompt" >> submissions.tsv, para que uma etapa posterior possa associar uma imagem finalizada ao prompt que a produziu.

Onde vão parar as imagens finalizadas?

openart creation wait e openart creation get retornam metadados do job e URLs dos assets em JSON, não os arquivos de imagem em si. Adicione uma etapa de download, como curl -o "results/${job_id}.png" "$url" usando a URL desse JSON, caso o fluxo de trabalho precise de arquivos em disco em vez de links.

Esse fluxo de trabalho em lote também funciona para geração de vídeo?

Sim. A CLI espelha os comandos de imagem para vídeo: openart generate video "<prompt>" --model kling-3-omni envia um job de vídeo da mesma forma openart generate image envia um job de imagem. Troque generate image por generate video no loop de envio, e o mesmo --json/--async flags mais openart creation wait/openart creation get o padrão de coleta deve se aplicar. Execute openart generate video --help para confirmar quaisquer flags específicas de vídeo (como duração) antes de programar um lote grande, já que os exemplos e testes deste tutorial cobrem especificamente a geração de imagens.