# Midjourney — /images/generations

El modelo de imagen Midjourney (Beta), V8.2 por defecto. Prompts y parámetros como en midjourney.com; cada trabajo es un juego de cuatro PNG originales cobrado una vez, y ampliar, variar, remix, zoom y desplazar usan el mismo endpoint.

**Endpoint:** `POST https://kovapi.com/v1/images/generations`

## Inicio rápido

Un trabajo asíncrono como las demás llamadas de imagen: envías, recibes un id y consultas el resultado. Los tres pasos de abajo son texto a imagen, el resultado y ampliar la imagen 2.

**Paso 1: envía texto a imagen (parámetros al final del prompt)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "speed": "fast"}'
```

Respuesta (HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1795248736,
  "model": "midjourney"
}
```

**Paso 2 · Consulta cada 2–3 segundos hasta que `status` sea `succeeded` o `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

data trae los cuatro PNG originales (en orden 1-4); actions lo que el trabajo puede hacer después.

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1795248736,
  "model": "midjourney",
  "data": [
    {"url": "https://img.kovapi.com/i/5b2c0e8a1f3d4c6b9a7e2d1c0b3a4f5e.png"},
    {"url": "https://img.kovapi.com/i/0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f.png"},
    {"url": "https://img.kovapi.com/i/7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d.png"},
    {"url": "https://img.kovapi.com/i/3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b.png"}
  ],
  "usage": {"images": 4, "model": "midjourney", "speed": "fast", "action": "imagine"},
  "actions": ["upscale", "vary", "remix", "reroll", "zoom", "pan"]
}
```

**Paso 3: continúa el trabajo — amplía la imagen 2 (mismo endpoint, con task_id, action e index)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "task_id": "img_7f3c9a1e2b4d6f8a0c1e3b5d", "action": "upscale", "index": 2, "mode": "subtle"}'
```

**Ejemplo completo (Python: enviar, esperar y guardar en disco)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def run(body):
    job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json=body).json()
    if "error" in job:
        raise SystemExit(job["error"]["message"])
    while job["status"] not in ("succeeded", "failed"):
        time.sleep(5)
        job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
    if job["status"] == "failed":
        raise SystemExit(job["error"]["message"])
    return job

# texto a imagen y luego ampliar la imagen 2
grid = run({"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2"})
print([d["url"] for d in grid["data"]], grid["actions"])
big = run({"model": "midjourney", "task_id": grid["id"], "action": "upscale", "index": 2})
with open("midjourney-2.png", "wb") as f:
    f.write(requests.get(big["data"][0]["url"]).content)
```

## Autenticación
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Parámetros

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| model | string | Sí | ID del modelo; aquí midjourney. |
| prompt | string | No | El prompt, con los parámetros de Midjourney al final como en midjourney.com (--ar, --v, --niji, --s, --c, --w, --seed, --no, --sref, --oref, --cref, --iw, --raw, --tile, --hd, --draft). Obligatorio para texto a imagen, remix y edit; hasta 6000 caracteres. --repeat y {a, b} no se admiten. |
| speed | string | No | `relax` (por defecto, $0.045), `fast` ($0.055) o `turbo` ($0.10). También sirve --relax / --fast / --turbo en el prompt; este campo manda. |
| images | array | No | Imágenes de referencia, hasta 5, como URL, data: URI o base64; van delante del prompt, como en Midjourney (pondéralas con --iw). Con action blend: las 2-5 imágenes a mezclar. |
| size | string | No | Una proporción (p. ej. `3:2`) o un tamaño en píxeles; se convierte en --ar si el prompt no lo trae (el --ar del prompt manda). Un edit sin ninguno de los dos mantiene la proporción de la imagen. |
| task_id | string | No | El trabajo que continúas (img_..., terminado, de hace menos de 7 días). |
| action | string | No | `upscale` (2x, mode subtle / creative), `vary` (strength strong / subtle), `remix` (un prompt nuevo), `reroll`, `zoom` (alejar 1-2), `pan` (direction), `inpaint` (mask); y sin task_id, `blend` (2-5 imágenes) y `edit` (una imagen y una instrucción). |
| index | integer | No | Qué imagen (1-4); opcional sobre una sola imagen ampliada. |
| n | integer | No | Debe ser 1: un trabajo es un juego de cuatro imágenes, cobrado una vez. |
| callback_url | string | No | Adónde enviar el resultado cuando termine el trabajo; consulta la sección de webhooks más abajo. |

## Acciones (task_id + action)

Continúa un trabajo terminado (de hace menos de 7 días), una acción por cada botón de la app oficial; el resultado es un trabajo nuevo, cobrado a la velocidad elegida.

| action | Campos | Qué hace |
| --- | --- | --- |
| upscale | index, mode | Amplía 2x: mode `subtle` (por defecto, mantiene los detalles) o `creative` (añade detalle); devuelve una imagen. |
| vary | index, strength | Cuatro variaciones de la imagen index: strength `strong` (por defecto) o `subtle`. |
| remix | index, prompt, strength | Mantiene la composición y la rehace según el prompt nuevo; cuatro imágenes. |
| reroll | — | Vuelve a generar el juego entero con el mismo prompt; cuatro imágenes. |
| zoom | index, zoom | Aleja la imagen: zoom 1-2 (por defecto 2); cuatro imágenes. |
| pan | index, direction | Amplía hacia left / right / up / down; cuatro imágenes. |
| inpaint | index, mask, prompt | Redibuja solo la zona blanca (o transparente) de la máscara; una máscara con la proporción de la imagen se escala a su tamaño. Disponible cuando las actions del trabajo incluyen inpaint. |
| blend | images (2-5) | Sin task_id: mezcla 2-5 imágenes en un juego de cuatro; pon la proporción en prompt (p. ej. `--ar 3:2`). |
| edit | image, prompt | Sin task_id: una imagen y una frase con el cambio (V8.2 / 8.1); cuatro imágenes con la proporción de la imagen, salvo que el prompt traiga --ar o pases size. |

## Precio

Se cobra por trabajo, un juego de cuatro imágenes (una al ampliar); las acciones cuestan lo mismo que un trabajo a la velocidad elegida. --hd (familia V8) cuesta el doble y un --draft de V7 la mitad (redondeado hacia abajo a créditos enteros); variar o regenerar un juego HD también cuesta el doble. Se reserva al enviar y se libera por completo si falla.

| Velocidad | Créditos por imagen | USD por imagen |
| --- | --- | --- |
| relax (por defecto) | 9 | $0.045 |
| fast | 11 | $0.055 |
| turbo | 20 | $0.10 |

## Tamaños, versiones y límites

- Recibes los PNG originales que generó Midjourney (con los metadatos de contenido que escribe Midjourney), sin recortes ni redimensionado. El tamaño sigue la proporción: 1:1 es 1024×1024, 3:2 es 1344×896, 16:9 es 1456×816; --hd y la ampliación son 2x.

- Versiones: V8.2 si no escribes ninguna; --v 8.1 / 8 / 7 / 6.1 / 6 o --niji 7 / 6. --hd solo para la familia V8 y --draft solo para V7 y V8 (un borrador V8 se cobra completo y puede traer 24 imágenes).

- --repeat / --r y las permutaciones {a, b} (una petición que se convierte en varios trabajos) no se admiten; n debe ser 1.

- Hasta 5 imágenes de referencia, delante del prompt como en Midjourney (ponderadas con --iw); las referencias de estilo van en --sref <URL>, las omni de V7 en --oref <URL>.

- Los resultados y las imágenes subidas se guardan 7 días; los trabajos más antiguos ya no se pueden continuar.

- Describe (de imagen a prompt) y el vídeo de Midjourney aún no están disponibles.

## Estado y campos del trabajo

`GET /v1/images/jobs/{id}` devuelve estos estados; cada campo se describe en [Trabajos asíncronos](https://docs.kovapi.com/es/guide/async-jobs#fields). Consulta cada 2–3 segundos o usa un webhook.

| Estado | Significado |
| --- | --- |
| queued | En cola. Incluye `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). |
| processing | Generándose. |
| succeeded | Terminado. El resultado está en `data[0].url` y el detalle del cobro en `usage`. |
| failed | Falló. El motivo está en `error`; los créditos reservados se devuelven íntegros. |

Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de las imágenes, 7 días.

## Cuánto tarda

Medido el 11-21: cuatro imágenes en unos 1,5-2 minutos con relax y fast, unos 1,5 con turbo; ampliar unos 2 minutos, zoom y desplazar unos 1,3; con imágenes de referencia o blend unos 4. En horas punta puede tardar más.

## Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en [Códigos de error](https://docs.kovapi.com/es/guide/errors).

### Errores al enviar

| HTTP | code | Causa | Qué hacer |
| --- | --- | --- | --- |
| 400 | invalid_request | No se puede leer una imagen de referencia (enlace roto, no es una imagen, supera 16MB...; `message` indica cuál y por qué), `/v1/images/edits` no lleva imagen de referencia, el cuerpo no es un objeto JSON o `n` no es un entero. | Corrige lo que indica `message` y vuelve a enviar la petición. |
| 400 | unsupported_action | No se puede leer una imagen de referencia (enlace roto, no es una imagen, supera 16MB...; `message` indica cuál y por qué), `/v1/images/edits` no lleva imagen de referencia, el cuerpo no es un objeto JSON o `n` no es un entero. | Corrige lo que indica `message` y vuelve a enviar la petición. |
| 404 | task_not_found | No se puede leer una imagen de referencia (enlace roto, no es una imagen, supera 16MB...; `message` indica cuál y por qué), `/v1/images/edits` no lleva imagen de referencia, el cuerpo no es un objeto JSON o `n` no es un entero. | Corrige lo que indica `message` y vuelve a enviar la petición. |
| 401 | invalid_api_key | La clave no existe, se eliminó o está desactivada, o la cuenta está desactivada. | Revisa la clave en la página API Keys de la consola. |
| 402 | insufficient_quota | No hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo. | Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga. |
| 429 | rate_limit_exceeded | Se superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera `Retry-After`. | Espera unos segundos y reintenta, o sube el límite de la clave en la consola. |
| 503 | service_unavailable | Un fallo temporal de nuestro lado, por ejemplo al guardar un archivo de referencia; `/v1/responses` también responde 503, con `Retry-After`, cuando no puede atender peticiones por un momento. | Reintenta en breve. |

### Trabajos fallidos (`status` `failed`)

| code | Cuándo aparece | Qué hacer |
| --- | --- | --- |
| moderation_blocked | Imagen: el sistema de seguridad del proveedor del modelo rechazó el prompt o una imagen de referencia (el código también puede ser `content_policy_violation`). | Reescribe el prompt o cambia la referencia; si se reenvía sin cambios, normalmente se vuelve a rechazar. |
| upstream_error | Cualquier otro fallo: los reintentos automáticos no bastaron, el trabajo esperó 15 minutos sin empezar, el proveedor lo rechazó sin dar motivo, etc.; `message` indica cuál. | Volver a enviarlo suele funcionar. |

## Webhooks en lugar de consultas

Añade `callback_url` al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. [Documentación de webhooks →](https://docs.kovapi.com/es/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "callback_url": "https://your-domain.com/webhook"}'
```
