Imagem

Duas rotas sobre o mesmo modelo: uma parte só de um prompt, a outra parte de imagens que você envia. As duas devolvem a imagem em base64 no corpo da resposta.

Geração#

application/json. Um prompt entra, um PNG sai.

curl -X POST "https://api.trystac.com/v1/images/generations" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a white dress shirt folded on a wooden table",
    "size": "1024x1024",
    "seed": 42
  }'

Esta rota não aceita imagem de entrada. Enviar uma devolve 400 wrong_route_for_reference_image — use /v1/images/edits.

Edição#

multipart/form-data. De uma a quatro imagens de referência, mais um prompt descrevendo a mudança.

curl -X POST "https://api.trystac.com/v1/images/edits" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F "prompt=make it black and white" \
  -F "size=1024x1024" \
  -F "image[]=@photo.png"

O campo de arquivo aceita tanto image quanto image[] — o segundo é o que os próprios exemplos da OpenAI usam para múltiplos arquivos. Até 4 imagens, de 5 MiB cada, em PNG, JPEG ou WEBP. O formato é lido do conteúdo do arquivo, não da extensão nem do Content-Type da parte. O corpo multipart inteiro tem teto de 21 MiB.

As imagens de referência são convertidas para RGB na chegada, o que descarta o canal alfa, perfis de cor e metadados EXIF — inclusive qualquer dado de localização que o arquivo original carregasse.

mask não é suportado e devolve 400. O pod carrega um único pipeline, e aplicar a edição na imagem inteira fingindo respeitar a máscara seria pior que recusar.

Parâmetros#

Os mesmos campos nas duas rotas — como JSON em /generations, como campos de formulário em /edits.

Resposta#

Idêntica nas duas rotas.

{
  "created": 1767225600,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "meta": {
    "prompt": "a white dress shirt folded on a wooden table",
    "width": 1024,
    "height": 1024,
    "steps": 4,
    "guidance_scale": 1.0,
    "seed": 8151234567890123456,
    "n": 1,
    "model": "flux2-klein-4b",
    "timings": {
      "queue_wait_s": 0.0100,
      "decode_s": null,
      "gpu_s": 4.1000,
      "encode_s": 0.1800,
      "worker_s": 4.2800
    }
  }
}

O meta traz os parâmetros efetivos — o que o servidor de fato usou, depois dos padrões e depois de sortear uma seed, se você não mandou uma.

Tamanho do prompt#

Esta é a causa mais comum de "a imagem ignorou metade do que eu pedi". Um prompt longo e detalhado não só é desperdiçado depois do corte, como também dilui a parte que cabe. Comece pelo assunto e pelos detalhes que mais importam.

Prompt na chave#

O prompt pode viver na sua chave de API, como o system prompt das rotas de texto — e vale a mesma precedência.

É o que permite mandar só a URL, a chave e a imagem:

curl -X POST "https://api.trystac.com/v1/images/edits" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F "image[]=@photo.png"

Vazão#

Geração de imagem não tem cota diária — difusão não produz tokens, então o orçamento de tokens que vale para as rotas de chat não se aplica aqui. O que limita é a GPU, que renderiza uma imagem por vez.

Os dois limites são da stack, não da chave. Emitir mais chaves não os aumenta, porque é a mesma GPU que faz o trabalho de qualquer jeito.

Observado de ponta a ponta: cerca de 6–9s para texto → imagem e 7–21s para uma edição, variando com a quantidade, as dimensões e o peso das imagens de referência. "10 por minuto" é teto de submissão, não promessa de dez imagens concluídas por minuto.

Armazenamento e retenção#

Toda imagem gerada é armazenada, ligada à conta, à stack e à chave que a criou. Isso acontece no servidor e não muda nada no seu código — a resposta continua sendo b64_json.

Duas consequências que vale conhecer:

• Um 200 significa que a imagem foi armazenada. A gravação acontece antes de a resposta sair e adiciona algumas centenas de milissegundos a uma chamada que já leva segundos.
• Um 502 pode acontecer com a imagem já gerada. Se o armazenamento falhar, devolvemos o erro em vez de entregar a imagem afirmando que ela foi guardada. Repetir é seguro — mas note que a requisição gera de novo, com uma seed nova se você não fixou nenhuma.

Os arquivos são mantidos por 30 dias. Se você precisa de uma imagem por mais tempo, guarde o b64_json do seu lado: este armazenamento existe para rastreabilidade e para a visualização na plataforma, não como hospedagem permanente.

Erros#

Dois formatos de erro chegam até você nestas rotas. As recusas do próprio gateway usam o formato { "detail": "..." } comum a toda a API; o que o servidor de imagem recusa volta no formato da OpenAI, com um code estável em que você pode ramificar:

{
  "error": {
    "message": "size must be one of: 1024x1024, 1536x1024, 1024x1536",
    "type": "invalid_request_error",
    "code": "invalid_size"
  }
}

Repita 429, 503 e 504 depois do tempo indicado no Retry-After. Um 502 também vale uma tentativa, lembrando que ele renderiza de novo do zero.