API Pro: gerar e retocar imagens
Uma imagem custa 1 crédito, independentemente do modo. A geração a partir de um prompt e o retoque de uma imagem que forneces passam pela mesma rota.
Submeter uma imagem
POST /images
{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
"width": 832, "height": 1216 }
| Campo | Tipo | Predefinição | O que faz |
|---|---|---|---|
prompt | string | obrigatório | A cena. Em inglês obtém os resultados mais precisos. |
width, height | int | 1024 x 1024 | Tamanho em píxeis. Formatos recomendados: 1024 x 1024 (quadrado), 832 x 1216 (retrato), 1216 x 832 (paisagem). |
mode | string | generation | edit, img2img ou inpaint, ver abaixo. Se ausente, gera a partir do prompt. |
image_b64 | string | Imagem de origem em base64 (PNG ou JPEG), obrigatória nos três modos de retoque. Máximo de 12 MB descodificados. | |
mask_b64 | string | Máscara em base64: obrigatória para inpaint, opcional para edit. Pinta a vermelho as áreas a retocar, com o tamanho da imagem de origem. | |
lora | string | Uma personagem treinada na conta: o name devolvido por GET /loras. Coloca o seu trigger no prompt. | |
lora2, lora2_strength | string, number | Uma segunda personagem e a sua intensidade (0 a 1, predefinição 1) para uma cena com duas pessoas. | |
steps | int | motor | Deixa vazio. O motor conhece o seu próprio valor. |
A resposta:
{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }
O seed é sorteado pelo motor e devolvido a título informativo. Não pode ser fixado na entrada nesta versão.
Os três modos de retoque
Os três funcionam com o mesmo motor de edição guiado por instruções, que preserva o aspeto da imagem de origem. Quando forneces uma imagem de origem, width e height são lidos a partir da própria imagem e não precisam de ser enviados.
mode | Entradas | O que o motor faz |
|---|---|---|
edit | image_b64 + prompt (+ mask_b64 opcional) | Aplica a instrução a toda a imagem ("add sunglasses", "make it snow"). Com uma máscara, a alteração concentra-se dentro da área vermelha. |
inpaint | image_b64 + mask_b64 + prompt | Regenera apenas a área vermelha da máscara, seguindo a instrução. O resto é recomposto píxel a píxel. |
img2img | image_b64 + prompt | Retrabalha toda a imagem com base no prompt, mantendo a sua composição e aspeto: uma variação. |
IMG=$(base64 -w0 photo.png)
curl -s $B/images -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d "{\"mode\":\"edit\",\"prompt\":\"add a red scarf, keep everything else identical\",\"image_b64\":\"$IMG\"}"
Polling
GET /images/{jobId}
| Resposta | Significado |
|---|---|
{ "status": "pending", "phase": "IN_QUEUE" } | Em fila de espera |
{ "status": "pending", "phase": "IN_PROGRESS" } | A renderizar |
{ "status": "completed", "cost": 1, "file_url": "/pro/v1/images/{jobId}/file", ... } | Concluído, ficheiro pronto |
{ "status": "failed", "detail": "..." } | Falhou, e nada é cobrado |
Faz polling a cada 3 segundos, não mais rápido: a fila é partilhada.
Transferência
GET /images/{jobId}/file
O próprio PNG, como corpo da resposta (Content-Type: image/png). Disponível assim que o estado for completed, e 404 media_indisponible quando o render já não estiver disponível. Transfere-o imediatamente, não fica arquivado.
Cancelar
POST /images/{jobId}/cancel
Cancela um render em fila ou em execução. Responde com { "ok": true }. Nada é cobrado e o custo reservado contra o limite diário da chave é devolvido.