Pro API: generar y retocar imágenes
Una imagen cuesta 1 crédito, sea cual sea el modo. La generación desde un prompt y el retoque de una imagen que aportas tú pasan por la misma ruta.
Enviar una imagen
POST /images
{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
"width": 832, "height": 1216 }
| Campo | Tipo | Valor por defecto | Qué hace |
|---|---|---|---|
prompt | string | requerido | La escena. El inglés da los resultados más precisos. |
width, height | int | 1024 x 1024 | Tamaño en píxeles. Formatos recomendados: 1024 x 1024 (cuadrado), 832 x 1216 (retrato), 1216 x 832 (paisaje). |
mode | string | generation | edit, img2img o inpaint, ver más abajo. Si se omite, genera a partir del prompt. |
image_b64 | string | Imagen fuente en base64 (PNG o JPEG), requerida por los tres modos de retoque. Máximo 12 MB decodificados. | |
mask_b64 | string | Máscara en base64: requerida por inpaint, opcional para edit. Pinta en rojo las zonas a retocar, con el tamaño de la imagen fuente. | |
lora | string | Un personaje entrenado en la cuenta: el name que devuelve GET /loras. Pon su trigger en el prompt. | |
lora2, lora2_strength | string, number | Un segundo personaje y su intensidad (de 0 a 1, por defecto 1) para una escena con dos personas. | |
steps | int | engine | Déjalo vacío. El motor conoce su propio valor. |
La respuesta:
{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }
El seed lo elige el motor y se devuelve a título informativo. En esta versión no puede fijarse como entrada.
Los tres modos de retoque
Los tres funcionan sobre el mismo motor de edición por instrucciones, que preserva el aspecto de la
imagen fuente. Cuando aportas una imagen fuente, width y height se leen de la propia imagen
y no hace falta enviarlos.
mode | Entradas | Qué hace el motor |
|---|---|---|
edit | image_b64 + prompt (+ mask_b64 opcional) | Aplica la instrucción a toda la imagen ("add sunglasses", "make it snow"). Con una máscara, el cambio se concentra dentro del área roja. |
inpaint | image_b64 + mask_b64 + prompt | Regenera únicamente el área roja de la máscara siguiendo la instrucción. El resto se recompone píxel a píxel. |
img2img | image_b64 + prompt | Reelabora toda la imagen siguiendo el prompt mientras conserva su composición y aspecto: una variación. |
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}
| Respuesta | Significado |
|---|---|
{ "status": "pending", "phase": "IN_QUEUE" } | En cola |
{ "status": "pending", "phase": "IN_PROGRESS" } | Renderizando |
{ "status": "completed", "cost": 1, "file_url": "/pro/v1/images/{jobId}/file", ... } | Listo, archivo disponible |
{ "status": "failed", "detail": "..." } | Fallido, y no se cobra nada |
Consulta cada 3 segundos como mínimo: la cola es compartida.
Descarga
GET /images/{jobId}/file
El propio PNG como cuerpo de la respuesta (Content-Type: image/png). Disponible en cuanto el
estado es completed, y devuelve 404 media_indisponible cuando el render ya no existe. Descárgalo
enseguida, no se archiva.
Cancelar
POST /images/{jobId}/cancel
Cancela un render en cola o en curso. Responde { "ok": true }. No se cobra nada y el coste
reservado frente al límite diario de la clave se devuelve.