Gerar imagens a partir de prompts de texto
🤖/image/generate gera imagens a partir de prompts de texto usando IA.

Exemplo de uso
Faça upload de uma origem de 1024×1024 no campo image e de uma máscara de edição correspondente, branca sobre preto, no campo mask. Este exemplo preserva todos os pixels decodificados da origem fora da máscara:
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"inpainted": {
"format": "png",
"inpainting": "strict",
"model": "google/nano-banana-pro",
"prompt": "Replace the masked area with a breaching whale. Keep the rest of the image unchanged.",
"robot": "/image/generate",
"use": [
{
"as": "image",
"fields": "image",
"name": ":original"
},
{
"as": "mask",
"fields": "mask",
"name": ":original"
}
]
}
}
}Parâmetros
interpolateboolean | Record<string, boolean>Controla se as Assembly Variables são interpoladas em campos individuais de instruções.
Por padrão, a maioria dos campos de instruções dos Robots interpola Assembly Variables. Defina isso como
falsepara tratar todos os campos de instruções como texto literal, ou defina o caminho de um campo individual comofalsepara tratar apenas esse campo como texto literal. Para campos específicos de um Robot que são literais por padrão, defina isso comotrueou defina o caminho desse campo comotruepara voltar a usar a interpolação.Use nomes de campos como
pathou caminhos com pontos comoffmpeg.vfpara objetos aninhados.output_metaRecord<string, boolean> | boolean | Array<string>Solicita metadados que exigem muito da CPU, desativados por padrão para deixar as Assemblies mais rápidas.
Para imagens,
"has_transparency": truedetecta transparência e"dominant_colors": trueextrai cores hexadecimais. Adicione"dominant_colors_sampled": truepara obter cores aproximadas e mais rápidas, a partir de quadros reduzidos. A amostragem exigedominant_colorse não altera os bytes da imagem nem a cobrança. O método e a paleta podem variar. Omita ou desative essa opção para obter cores em resolução total.Para imagens, você também pode adicionar
"blurhash": truepara extrair uma string BlurHash, uma representação compacta de um placeholder da imagem, útil para exibir uma prévia desfocada enquanto a imagem completa carrega.Para imagens,
"thumbhash": trueextrai, em vez disso, um ThumbHash codificado em base64 emmeta.thumbhash, junto commeta.has_alpha(se existe um canal alfa, mesmo quando totalmente opaco). Ele descreve pixels orientados por EXIF e usa o primeiro quadro de imagens animadas. A extração é feita em regime de melhor esforço: imagens acima de 40 megapixels, formatos sem suporte ou uma decodificação com falha ou limitada não geram placeholder. Uma extração bem-sucedida adiciona uma cobrança de metadados equivalente a 20% dos bytes desse arquivo. Nenhuma sobretaxa de ThumbHash se aplica quando a opção está desativada ou quando nenhum hash é gerado.Defina essa opção no Step que produz a imagem, como
/upload/handlepara originais enviados por upload ou/image/resizepara saídas processadas. Defini-la apenas em/transloadit/storenão solicita a extração: o armazenamento preserva os metadados do produtor. O Transloadit Storage persiste um hash gerado com sua versão imutável e o retorna em resultados armazenados e em leituras nativas de ativos. Uploads diretos para o S3 não geram placeholders. Um placeholder contém informações da imagem, portanto proteja-o com os mesmos controles de acesso da imagem completa.Para vídeos, você pode adicionar o parâmetro
"colorspace": truepara extrair o espaço de cores do vídeo de saída.Para vídeos, você também pode adicionar
"interlaced": truepara detectar se o vídeo é entrelaçado. Isso combina a flag barata do ffprobefield_ordercom uma passagem de amostragemidetlimitada sobre os primeiros quadros da origem, expondointerlaced,field_ordere um objeto de diagnósticointerlace_detectionemfile.meta. Isso é computacionalmente caro e cobrado de acordo.Para áudio, você pode adicionar
"mean_volume": truepara obter um único valor que representa o volume médio do arquivo de áudio.Você também pode definir isso como
falsepara pular a extração de metadados e acelerar a transcodificação.user_metaRecord<string, any>(padrão:{})Adiciona metadados JSON personalizados a cada arquivo emitido sem modificar seu conteúdo. Objetos e arrays aninhados são suportados.
A herança depende do Robot. Os valores são mesclados com o
user_metaexistente no arquivo de saída; o Step atual substitui as chaves de nível superior com o mesmo nome. Atribua explicitamente as chaves necessárias quando um Robot criar novas saídas.Nos Steps de processamento,
${file.*}se refere à primeira entrada e${result.*}ao arquivo emitido. Os valores são avaliados para cada saída após a execução do Robot, antes da extração subsequente de metadados e do armazenamento temporário. Em:original, os valores são avaliados para cada upload antes da extração de metadados.Os Steps subsequentes leem
${file.user_meta.key}. Consulte Metadados personalizados para ver um exemplo completo e as regras de herança.resultboolean(padrão:false)Se os resultados deste Step devem estar presentes no Assembly Status JSON
queuebatchDefinir a fila como “batch” rebaixa manualmente a prioridade dos Jobs deste Step, para evitar o consumo de vagas prioritárias de Jobs em Jobs que não precisam de tempo zero de espera na fila
force_acceptboolean(padrão:false)Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.
Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.
Com o parâmetro
force_acceptdefinido comotrue, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.ignore_errorsboolean | Array<meta | execute>(padrão:[])Ignorar erros durante fases específicas do processamento.
Definir isso como
["meta"]fará com que o Robot ignore erros durante a extração de metadados.Definir isso como
["execute"]fará com que o Robot ignore erros durante a fase principal de execução.Definir isso como
trueequivale a["meta", "execute"]e fará com que erros sejam ignorados nas duas fases.usestring | Array<string> | Array<object> | objectEspecifica quais Steps usar como entrada.
Para inpainting, selecione a origem e a máscara por meio de campos de upload ou das funções
use.as.Vários seletores de origem falham com “Supply exactly one inpainting source image.” Seletores de edição concorrentes, inclusive as duas funções de edição em uma mesma entrada, falham com “Supply exactly one inpainting mask or cutout.” Um campo de edição substitui as funções de edição herdadas.
Formas de entrada aceitas:
- Selecione campos de imagem e de máscara/recorte. Os campos substituem as funções herdadas.
- Sem campos, use as funções de imagem e de máscara/recorte. Entradas use repetidas combinam as funções.
- Combine um campo de imagem com uma função de edição, ou uma função de imagem com um campo de edição.
- Com um seletor de edição, mas sem seletor de imagem, a primeira entrada que não for máscara é a origem.
- Um recorte transparente com intenção de imagem é a sua própria origem, inclusive ao lado de referências.
- Pares legados de imagem+máscara usam a primeira origem marcada e a segunda máscara marcada; as referências não afetam a seleção. Os campos prevalecem.
- A Replicate aceita 3 ou mais uploads de imagem+máscara, usa os dois primeiros, a menos que campos os selecionem, e ignora as referências.
- Somente a Replicate aceita entradas sem marcação, com a origem primeiro e a máscara depois, respeitando um seletor de imagem único.
- O modo strict aceita uma única imagem transparente, inclusive um upload só de máscara, como origem e recorte; best_effort recusa a forma só de máscara.
- As demais entradas continuam sendo referências. Transparência sem marcação nunca ativa a edição best_effort do Google/OpenAI. Marque máscaras/recortes com um campo ou com uma função use.as.
Formatos de máscara (a origem e a máscara devem ter dimensões iguais):
- Máscaras opacas em preto e branco editam o branco e protegem o preto (limite da média de RGB: 128). Use preto e branco para evitar cores opacas ambíguas.
- Uma máscara com transparência edita pixels com alfa abaixo de 128 e protege o restante.
- Máscaras verdes legadas editam pixels com alfa de pelo menos 128 quando todos esses pixels são verdes (verde de pelo menos 128 e maior que vermelho e azul). Pixels transparentes são protegidos.
- Um recorte edita o alfa abaixo de 128. Uma origem separada fornece os pixels protegidos; caso contrário, só os pixels restantes do recorte podem ser preservados. Junto com referências, dê ao recorte um campo ou uma função de imagem para selecioná-lo como origem.
A origem e a máscara devem ser rasters com dimensões de exibição iguais, com no máximo 40.000.000 pixels cada (16.777.216 no modo strict). O modo strict recusa SVG/SVGZ; a decodificação best_effort os desenha uma única vez. O modo best-effort aplica a orientação EXIF e usa o primeiro quadro; o modo strict exige um único quadro e a orientação aplicada.
As máscaras são convertidas para cada provedor. Modelos de inpainting compatíveis:
google/nano-banana,google/nano-banana-2,google/nano-banana-pro,openai/gpt-image-2,openai/gpt-image-2.5-flare,openai/gpt-image-2.5-sunburst,openai/gpt-image-2.6-flare,openai/gpt-image-2.6-sunburst,stability-ai/stable-diffusion-inpainting. O alias legadogpt-image-2usa a mesma rota da OpenAI. FLUX, Recraft e o Stable Diffusion legado auto-hospedado não têm rota de inpainting aqui; as solicitações de inpainting são recusadas em vez de ignorar a máscara silenciosamente. A geração comum, sem máscara, mantém o comportamento existente.Sem o modo strict, a imagem completa do provedor é retornada; as máscaras apenas a orientam. O conteúdo externo, as cores, o tamanho ou a transparência podem mudar, mesmo com uma seed fixa. Selecione strict para obter os pixels externos exatos. Imagens auxiliares, como mapas de ganho, não são mantidas na saída PNG do modo strict.
O modo strict usa o canvas da origem sem redimensionar. O Google exige um canvas nativo: em 1K, o Nano Banana aceita 1024×1024, 864×1184, 1184×864, 768×1344 ou 1344×768; o Nano Banana Pro e o Nano Banana 2 aceitam 1024×1024, 896×1200, 1200×896, 768×1376 ou 1376×768, e também tamanhos de 2× e 4× dentro do limite de pixels. As bordas do canvas da OpenAI devem ser múltiplos de 16, com no máximo 3840 pixels, proporção de no máximo 3:1 e de 655.360–8.294.400 pixels no total. O inpainting da Replicate exige que cada borda seja múltiplo de 64, de 64 a 1024 pixels. Canvases incompatíveis falham antes da geração; um resultado do provedor inesperadamente diferente também falha. Se necessário, redimensione a origem e a máscara juntas em um Step anterior.
modelstringO modelo de IA a ser usado. O padrão é
openai/gpt-image-2.5-flare. Os modelos compatíveis incluemflux-1.1-pro-ultra,flux-schnell,recraft-v3,google/nano-banana,google/nano-banana-2,google/nano-banana-pro,openai/gpt-image-2,openai/gpt-image-2.5-flare,openai/gpt-image-2.5-sunburst,openai/gpt-image-2.6-flare,openai/gpt-image-2.6-sunburstestability-ai/stable-diffusion-inpainting. O alias legadogpt-image-2também é aceito para compatibilidade com versões anteriores.prompt— obrigatóriostringPrompt que descreve a imagem desejada. Para inpainting, descreva o que deve aparecer na região mascarada/transparente e indique que o restante deve permanecer inalterado.
formatjpeg | jpg | png | webp | svgFormato de saída. Os padrões dependem do modelo: png para os modelos do Google e da OpenAI, svg para recraft-v3, jpeg para os demais. O Google pode retornar bytes JPEG no modo best_effort mesmo quando png é solicitado; o modo strict codifica PNG localmente.
inpaintingbest_effort | strict(padrão:"best_effort")best_effort normaliza as máscaras e retorna o resultado completo do provedor. strict copia o RGBA decodificado da origem fora da máscara com limiar rígido e o RGBA do provedor dentro dela, preservando o alfa; sem suavização de bordas nem chamada extra de IA. O modo strict exige canvases raster compatíveis, formato png, origem/saída sRGB de 8 bits e de quadro único, sem perfis incorporados, e orientação já aplicada. As máscaras podem ser em tons de cinza de 8 bits, sem perfis. Cada imagem é limitada a 16.777.216 pixels. Planos com marca d’água são recusados. Largura/altura devem corresponder à origem; dimensões omitidas usam o tamanho dela. Omita aspect_ratio. Aplicam-se os limites de canvas nativos do modelo. Entradas ou resultados incompatíveis falham. Os metadados PNG e os bytes do arquivo podem mudar; redimensionamento, marca d’água ou codificação com perdas posteriores podem alterar os pixels.
seedstring | numberSemente para o gerador de números aleatórios. Para modelos do Google, use um número inteiro de 0 a 2147483647. Cada resultado incrementa a semente em 1, portanto a semente do último resultado também deve estar nesse intervalo. Uma semente não garante imagens idênticas.
aspect_ratiostringProporção de saída solicitada. Para os modelos do Google, também é possível usar largura/altura, e a orientação é derivada automaticamente quando aspect_ratio é omitido.
heightstring | numberAltura de saída solicitada em pixels (usada principalmente pelos modelos de imagem do Google e da OpenAI).
widthstring | numberLargura de saída solicitada em pixels (usada principalmente pelos modelos de imagem do Google e da OpenAI).
stylestringEstilo da imagem gerada.
num_outputsstring | numberNúmero de variantes de saída a gerar (de 1 a 10).