API Pro: 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 tú aportes pasan por la misma ruta.

POST /images/quote acepta el mismo cuerpo y devuelve el precio sin crear nada, siempre { "cost": 1, ... } en este caso. Existe por simetría con los vídeos, donde el precio sí varía.

Enviar una imagen

POST /images

{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
  "width": 832, "height": 1216 }

La respuesta:

{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }

La seed se devuelve en la respuesta, tanto si la indicaste tú como si se generó aleatoriamente: guárdala para renderizar la misma imagen de nuevo o una variación de ella.

Pedir varias a la vez

Con count mayor que 1, una sola solicitud inicia varios renders, cada uno con su propia semilla, y la respuesta los lista:

{ "count": 4, "requested": 4, "cost_total": 4,
  "jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
  "errors": [],
  "jobId": "...", "seed": 178078967, "cost": 1 }

Dos cosas que conviene leer con atención.

El jobId, la seed y el cost del primer render se repiten en el nivel superior. Esto existe para que los clientes escritos antes de que existieran los lotes sigan funcionando sin cambios, no porque el primero importe más. Sondea cada entrada de jobs, no solo esa.

Y compara count con requested. Un rechazo a mitad del proceso, por falta de créditos o porque la clave alcanzó su límite diario, detiene el lote donde está: requested es lo que pediste, count es lo que realmente se inició, y errors explica por qué se detuvo. Un cliente que asume que ambos son iguales pierde renders en silencio.

POST /images/quote también acepta count y calcula el precio de todo el lote. Los vídeos no tienen count: una solicitud, un clip.

Los tres modos de retoque

Los tres funcionan sobre el mismo motor de edición basado en 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 es necesario enviarlos.

En edit, el servidor elige solo la mejor forma de tratar el retoque, como la app:

• con máscara: lee la instrucción y elige entre reemplazar el contenido de la zona (otro objeto, otra prenda, una cara: la zona se redibuja según lo que debe aparecer en ella) y modificar lo que hay (color, material, luz). Con un lora de personaje, la zona siempre se redibuja, cara incluida;
• sin máscara, con un lora de personaje ("replace the woman with kara..."): el servidor encuentra a la persona de la foto y la redibuja con el personaje; si no encuentra a nadie, la instrucción se aplica a toda la imagen, como antes.

Mismo precio en todos los casos (1 crédito por imagen). La elección se ve en el resultado, no en la respuesta.

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\"}"

Crear una imagen con personajes, objetos y un decorado

Añade un objeto multiref a POST /images y el servidor hace actuar a tus personajes (Personajes), tus objetos y animales y un decorado (Sujetos) juntos en una sola imagen, cada uno reconocible, como la pantalla «Crear una imagen» de la app. Llama a cada uno por @Nombre en el prompt, en inglés.

{ "prompt": "@Mia hands a cup of coffee to @Tom on a sunny terrace, both smiling",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Mia", "view": 1 },
      { "character_id": "chr_21bc...", "name": "Tom", "lora": "tom_v1", "strength": 1.0, "lora_pass": 0.55 }
    ],
    "subjects": [ { "subject_id": "sub_...", "name": "Mug" } ],
    "location": { "subject_id": "sub_...", "name": "Terrace" }
  },
  "width": 1344, "height": 768, "seed": 42, "count": 1 }

• 4 sujetos como máximo (personajes, objetos y animales). Sin LoRA, solo a partir de imágenes: 4 referencias como máximo, decorado incluido. El servidor elige el método según las referencias, y coloca cada una en el orden de characters y luego de subjects, de izquierda a derecha.
• Un @Nombre que no coincide con ninguna referencia se rechaza (unknown_mention); una referencia ausente del prompt se envía de todos modos.
• Precio: una pasada cuesta el precio de una imagen (1 crédito). Una imagen simple es 1 pasada; varios personajes interpretados por un LoRA, 1 más una pasada por LoRA (4 como máximo); solo a partir de imágenes, una pasada por referencia más allá de la primera; una mezcla, ambas cosas. El total (pasadas x count) se reserva al enviar y se descuenta una sola vez, con la imagen final: un fallo o una cancelación no cuesta nada. POST /images/quote con el mismo cuerpo da el precio exacto, el método y sus pasadas, sin iniciar nada.
• Respuesta 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" } (con count 2: jobs y cost_total). El sondeo, la descarga y la cancelación usan las rutas habituales de más abajo; durante el render, progress indica la pasada en curso ("2/3"). Una imagen tarda de 1 a 3 minutos.
• La imagen final sigue disponible 1 hora, y 10 minutos después de su primera descarga. Una pasada fallida da status: "failed" con reason: "render_failed"; una cancelación, reason: "cancelled".
• Errores: invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size, character_not_ready, más los de Multi-Ref (unknown_character, unknown_subject, unknown_lora, unknown_mention, multiref_too_many_references, invalid_strength...). Ver Límites y errores.

Sondeo

GET /images/{jobId}

Sondea cada 3 segundos, no más rápido: la cola es compartida.

Descarga

GET /images/{jobId}/file

El PNG en sí, como cuerpo de la respuesta (Content-Type: image/png). Disponible en cuanto el estado sea completed, y 404 media_unavailable una vez que el render haya desaparecido. Descárgalo de inmediato, no se archiva.

Cancelar

POST /images/{jobId}/cancel

Cancela un render en cola o en ejecución. Responde { "ok": true }. No se cobra nada, y el coste reservado contra el límite diario de la clave se devuelve.