01
A seed helps compare runs, not guarantee identical pixels
Where seed exists, keep it with the prompt, model version, size and references. Some endpoints remain nondeterministic; the same seed can still produce a different image.
Solução de API de imagem
Gere imagens com os controles que o modelo realmente expõe.
Cada endpoint de imagem declara os próprios campos: uns aceitam prompt negativo, outros semente, outros devolvem quatro candidatas por chamada. Um formulário genérico esconde exatamente os controles que tornam um resultado reproduzível.
O desafio
Formulários genéricos perdem os controles que importam
«Prompt entra, imagem sai» vale uns dez segundos. Depois você precisa do mesmo personagem uma segunda vez, 3:2 em vez de quadrado, quatro candidatas por chamada e uma semente que dê para anotar.
02
Tamanho é campo, não predefinição
Alguns endpoints aceitam resolution ou aspect_ratio; outros, width e height em pixels. Mandar o errado dá 400, e onde se cobra por megapixel o tamanho escolhido é também o preço.
03
Uma chamada pode devolver várias imagens
Onde existe num_outputs, a cobrança segue o número de imagens e não o de requisições. Um padrão de 4 custa quatro vezes um de 1, e essa diferença só aparece antes do envio na estimativa.
A abordagem
Leia o esquema, mantenha os campos, registre a semente
Build inputs from the endpoint schema. Save the exact request, ordered references and model version with the result so you can compare later variations. Keep accepted originals; regenerating them is not guaranteed.
Tarefas de imagem usam o mesmo contrato de criar e acompanhar que vídeo. A diferença inteira mora dentro de input.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-image",
"input": {
"prompt": "A ceramic teapot on linen, soft window light, muted palette",
"aspect_ratio": "3:2",
"num_outputs": 2,
"seed": 1337
}
}GET /api/v1/jobs/recordInfo?taskId=…
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "succeeded",
"output": {
"assets": [
{
"mime": "image/png",
"url": "https://…/result.png?X-Amz-Signature=…",
"expiresAt": "2026-09-12T12:20:08Z"
}
]
},
"cost": "0.040000",
"settled": true
}
}Contrato
O que vale fixar logo de início
| Campo ou cabeçalho | Valor ou limite |
|---|---|
| input | additionalProperties: false |
| seed · num_outputs · aspect_ratio | declared per endpoint |
| cost + settled: false | hold · final charge never exceeds it |
| errorCode | 9 stable values, content_rejected included |
Deslize horizontalmente para ver todas as colunas.
Integração
Da primeira chamada até produção
- 01Abra a página do modelo e veja quais entre seed, negative_prompt, num_outputs e campos de tamanho estão declarados.
- 02Monte o corpo pelo input_schema; additionalProperties está fechado, então uma chave não declarada é 400 e não silêncio.
- 03Estime, envie com Idempotency-Key e guarde taskId, semente e o valor model resolvido junto do resultado.
- 04Pegue output.assets no retorno ou no recordInfo e copie os arquivos para o seu próprio bucket.
Adequação
Quando este caminho é o certo
Escolha se
- Você gera a partir de texto e quer vários criadores atrás de uma única forma de requisição, um saldo e uma fatura.
- You need to compare controlled variations with a recorded request and model version.
Procure outro caminho se
- Seus usuários partem de uma foto que já têm. Edição é outra tarefa, com contrato de referência próprio.
- Você quer um estilo único da casa em todos os modelos. Estilo mora no modelo, não nesta camada.
Evidências
O que você mesmo pode verificar
A requisição de teste é a de produção
O corpo montado na página do modelo é o que o seu servidor envia: mesmos campos, mesma validação, mesma estimativa. Não existe prévia simplificada que depois divirja.
Campos não declarados falham alto
A entrada é validada contra o esquema do endpoint com additionalProperties fechado. Um parâmetro não declarado devolve 400 com errorCode estável em vez de ser ignorado.
As saídas vêm do armazenamento da plataforma
Os resultados chegam em output.assets com key, tipo MIME, url assinada e expiresAt. Nada aponta para onde o modelo rodou.
Antes de lançar
Comportamentos da plataforma a confirmar
- Decida antes do lançamento onde as sementes ficam guardadas; semente não guardada não serve para nada.
- Defina o teto diário obrigatório em cada chave nova e acrescente tetos mensal e acumulado quando fizer sentido.
- Trate o conjunto fechado de errorCode, content_rejected incluído, como estados normais do produto.
- Espelhe os arquivos para o seu armazenamento dentro da janela de 14 dias.
Perguntas frequentes
O que mais perguntam nesta página
Reuse the original input, version and seed if available. This narrows the comparison but does not guarantee identical pixels. Download and keep the original output when you need that exact image.
Em endpoints que declaram num_outputs, sim, e a cobrança escala com a quantidade. Estime o corpo para ver o valor da quantidade que pretende enviar.
Os que o endpoint declarar: resolution, aspect_ratio, ou width e height. A página do modelo lista os valores válidos e o resto é recusado antes de a tarefa existir.
A plataforma não acrescenta nenhum. O comportamento vem do modelo escolhido, e uma recusa chega como tarefa terminal comum com errorCode content_rejected.
Modelos
Modelos que você pode chamar para isso
Cada link abre a página daquela família de modelos: entradas, limites, política de conteúdo e o preço atual por unidade.
ByteDanceSeedream 5.0 ProTexto para imagemPolítica de conteúdo: Sem censuraAlibabaQwen Image 2.1Edição de imagemPolítica de conteúdo: Sem censuraByteDanceSeedream 5.0 FlashTexto para imagemPolítica de conteúdo: Sem censuraAlibabaQwen Image Edit SpicyEdição de imagemPolítica de conteúdo: Sem censuraAlibabaZ-Image Spicy ProTexto para imagemPolítica de conteúdo: Sem censuraAlibabaQwen Image 3.0 ProEdição de imagemPolítica de conteúdo: Sem censura
A seguir
Comparar endpoints de imagem lado a lado
Compare endpoints de imagem por entradas, controles de tamanho e semente, número de saídas e preço por imagem, e reutilize a requisição testada.