Midjourney no tiene una API pública oficial; en la práctica, lo que se integra suele ser un servicio de encapsulamiento de terceros. Las rutas, los campos y las máquinas de estados no son uniformes entre proveedores, pero el flujo de fondo es parecido: se envía una tarea y se obtiene un ID, se consulta el estado, se descarga la imagen cuando termina y, si hace falta, se amplía o se generan variaciones. Este artículo sigue esa cadena y se centra en las diferencias que suelen causar problemas y en los límites de cumplimiento.

Aviso de marcas: Midjourney es una marca de Midjourney, Inc.; Discord es una marca de Discord Inc. Este artículo solo ofrece una explicación técnica y no representa ninguna relación de cooperación, representación o aval. Midjourney no ofrece actualmente una API oficial; los términos y la estabilidad de las interfaces de terceros deben verificarse por cuenta propia.

1. Primero el proveedor, después el código

Las interfaces de terceros para Midjourney no siguen un estándar único. Aunque todas «envían una tarea», unas devuelven task_id y otras job_id; unas usan /imagine y otras /v1/midjourney/imagine; algunas convierten las ampliaciones y variaciones en tareas independientes y otras usan una interfaz de acciones. Antes de elegir, confirma seis puntos:

  • Si el método de autenticación y la URL base son estables y si las rutas están versionadas.
  • Qué tipos de tarea admite: texto a imagen, ampliación, variación, remezcla, redibujo y descripción.
  • Los campos de estado y los valores finales, y si distingue éxito, fallo, rechazo por moderación y tiempo agotado.
  • Cuánto tiempo conserva los resultados y qué límites de descarga aplica; si admite callbacks.
  • Las reglas de concurrencia, cola y límite de solicitudes, y si cobra los fallos.
  • La continuidad y el mecanismo de salida del proveedor, y si acepta contratos cortos y eliminación de datos.

Cuanto más se parezca la interfaz a tu sistema actual, menor será el costo de migración. No te fijes solo en la demostración: revisa primero la documentación de códigos de error y la capacidad de consultar tareas.

2. Autenticación y convenciones de solicitud

Lo habitual es colocar la clave de API en un encabezado y enviar un cuerpo JSON. El encabezado exacto depende de la documentación del proveedor; las formas comunes incluyen Authorization: Bearer, X-API-Key o encabezados personalizados. Guarda la clave, la URL base y el tiempo de espera en la configuración, no dispersos por el código.

Antes de llamar, confirma tres cosas: si el entorno es de pruebas o de producción, si la clave está vinculada a una IP o a un límite de consumo, y si la solicitud pasa por el proxy de salida de la empresa. Muchos 401 y 403 no se deben a una clave incorrecta, sino a un entorno mal configurado o a un proxy que reescribe los encabezados.

3. Enviar la tarea: prompt y parámetros

Una solicitud de envío típica es la siguiente; los campos son solo un ejemplo:

export MJ_API_KEY="your-provider-key"
export MJ_BASE_URL="https://provider.example.com"

curl -sS -X POST "$MJ_BASE_URL/v1/midjourney/imagine" \
  -H "Authorization: Bearer $MJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "minimalist product photo of a ceramic cup, soft window light --ar 4:3",
    "aspect_ratio": "4:3",
    "callback_url": "https://api.example.com/callbacks/mj"
  }'

No todos los proveedores procesan igual los parámetros --ar, --v y --style del prompt. Algunos separan la relación de aspecto en un campo propio y otros leen el prompt directamente; no supongas que los parámetros surtirán efecto y compruébalo en el detalle de la tarea devuelta.

En cuanto el envío se complete, registra de inmediato en tu tabla de tareas el ID de tarea, el número de pedido interno, el prompt, los parámetros, la hora de envío y el operador. El sondeo, los reintentos, la conciliación y la asignación de costos posteriores dependen de ese registro.

4. Sondeo: máquina de estados y retroceso

Estado Significado Acción recomendada
queued En cola Seguir esperando; evitar envíos duplicados
running Generando Consultar con una estrategia de retroceso
succeeded Éxito Leer el resultado y copiarlo de inmediato
failed Fallo Registrar el código de error y decidir si se puede reintentar
moderated Rechazo por moderación Modificar el prompt; no reintentar tal cual
expired Tiempo agotado o enlace vencido Revisar el detalle de la tarea y reenviar si es necesario

Empieza a consultar cada 3 a 5 segundos, aumenta gradualmente el intervalo hasta 15 o 30 segundos y define un tiempo máximo total. No consultes cada segundo ni permitas que varias instancias revisen la misma tarea a la vez. Cuando la tarea llegue a un estado final, detén el sondeo y guarda en la base de datos el estado final y la dirección del resultado.

Si el proveedor admite webhooks, puedes usarlos como notificación principal, pero debes verificar la firma, aplicar idempotencia y mantener el sondeo periódico como respaldo. La pérdida de callbacks no es rara en servicios de encapsulamiento.

5. Descarga y almacenamiento

La dirección de la imagen que se devuelve al completarse la tarea suele tener vigencia limitada: puede durar minutos, días o ser una URL firmada temporal. No la escribas directamente en una página de frontend ni la entregues al cliente.

El orden correcto es: al recibir el estado de éxito, descarga de inmediato, copia el archivo a tu propio almacenamiento de objetos, registra el ID de tarea, la ruta del objeto, el tamaño, el valor de verificación y la hora de descarga, y luego escribe la dirección interna en la base de datos del negocio. La descarga debe tener tiempo de espera, reintentos y un límite de concurrencia; para imágenes grandes conviene usar un proxy del servidor y evitar problemas de CORS y filtraciones de enlaces en el navegador.

Midjourney suele devolver una cuadrícula de cuatro imágenes y, además, imágenes individuales ampliadas. Al almacenar, nombra por separado la cuadrícula y las ampliaciones y conserva el ID de la tarea original, para poder relacionarlas cuando generes variaciones o redibujos más adelante.

6. Ampliaciones, variaciones y redibujo

Las ampliaciones y variaciones suelen depender del ID de la tarea original y del índice de la imagen. La forma común es enviar una tarea nueva con task_id e index, o llamar a la interfaz de acciones del proveedor. El índice puede empezar en 1 o en 0 según el proveedor, así que confírmalo con una tarea de prueba antes de integrarte.

Algunas recomendaciones prácticas:

  • Registra la «tarea original» y las «tareas derivadas» con una relación padre-hijo para no ampliar la misma imagen dos veces.
  • Una variación puede producir una nueva cuadrícula y se cobra como una tarea nueva; calcula el costo antes de procesar lotes.
  • El redibujo, el redibujo parcial y la mezcla no están disponibles en todos los proveedores; guíate por la documentación.
  • Las imágenes ampliadas también pueden estar sujetas a la vigencia del enlace upstream; guárdalas en cuanto la tarea termine.

7. Límites, concurrencia y costo

El rendimiento de un servicio de encapsulamiento depende del grupo de cuentas y de la cola upstream, no de la concurrencia que hayas comprado. Los límites habituales incluyen tareas por minuto, tareas simultáneas y cuota diaria por cuenta. Ante un 429, reduce la concurrencia y aplica retroceso exponencial; no reintentes sin control.

Calcula el costo sobre las «imágenes entregadas con éxito», no sobre el número de envíos. Incluye en el denominador los fallos, los rechazos por moderación, los envíos duplicados y las ampliaciones o variaciones para obtener el costo real por imagen. Ejecuta primero un lote pequeño, confirma la tasa de éxito y el tiempo promedio, y luego escala poco a poco.

8. Errores comunes y diagnóstico

  • 401: falta la clave, el formato es incorrecto, el entorno no coincide o la cuenta upstream dejó de ser válida.
  • 403: la IP no está en la lista permitida, no hay saldo o el permiso no está habilitado.
  • 404: la ruta o el ID de tarea son incorrectos, o la tarea ya fue eliminada.
  • 429: se activó el límite de solicitudes; reduce la concurrencia y aplica retroceso.
  • 5xx: fallo del proveedor upstream o de la capa de encapsulamiento; usa la clave de idempotencia para confirmar que la tarea no se creó antes de reintentar.
  • Tarea failed: revisa el código de error y distingue entre parámetros, moderación y fallo upstream.
  • Enlace 403/404: la dirección del resultado venció o requiere autenticación; vuelve al detalle de la tarea para obtenerla de nuevo.

Registra en los logs el ID de solicitud, el ID de tarea, el código de error y los parámetros enmascarados. Los mensajes de error de los servicios de encapsulamiento suelen estar reempaquetados; conservar la respuesta original reduce mucho el tiempo de diagnóstico.

9. Lista de verificación para migrar

Si pasas de un proveedor a otro, o de un proxy autoalojado a un servicio administrado, confirma punto por punto:

  1. Si se reemplazan en conjunto la URL base, el encabezado de autenticación y la ruta de solicitud.
  2. Si coinciden el nombre del campo del ID de tarea, los valores de estado y la detección del estado final.
  3. Si los parámetros del prompt se transmiten tal cual o se separan en campos, y si --ar y --v surten efecto.
  4. Si coinciden las formas de llamada y las reglas de índice para ampliaciones, variaciones y redibujo.
  5. Si se verificaron la vigencia de los enlaces de resultado, los límites de descarga y la lógica de almacenamiento.
  6. Si se admite callback y si la verificación de firma y la idempotencia están implementadas.
  7. Si se volvieron a probar bajo carga los límites, la concurrencia, los tiempos de espera y los reintentos.
  8. Si cuadran la unidad de facturación, los reembolsos por fallo y la conciliación de facturas.

Después de migrar, ejecuta primero un lote de tareas reales, compara la tasa de éxito, el tiempo promedio y el costo por imagen, y luego cambia el tráfico completo. Si no tienes conciliación y plan de reversión, no hagas el cambio de una sola vez.

Preguntas frecuentes

¿La API de Midjourney devuelve la imagen de forma sincrónica?

Normalmente no. El envío solo devuelve un ID de tarea; hay que consultar el estado o esperar un callback y, cuando termina, descargar la imagen. Diseñar la integración como una interfaz sincrónica suele provocar tiempos agotados y envíos duplicados.

¿Cuánto tiempo hay que consultar el estado de una tarea?

Depende de la cola y de la carga upstream; lo común va de decenas de segundos a varios minutos. Se recomienda empezar cada 3 a 5 segundos, aumentar el intervalo de forma gradual y definir un tiempo máximo; al agotarse, revisa el detalle de la tarea en lugar de reenviarla de inmediato.

¿Cuánto tiempo se conservan los enlaces de las imágenes?

Varía mucho entre proveedores: pueden ser minutos, horas o días. En producción no dependas de los enlaces upstream; guarda la imagen en tu propio almacenamiento de objetos en cuanto la tarea termine.

¿Cómo se llaman las ampliaciones y las variaciones?

Por lo general necesitas el ID de la tarea original y el índice de la imagen, y luego envías una tarea derivada o llamas a la interfaz de acciones. El valor inicial del índice y los nombres de campo cambian según el proveedor; confírmalos con una tarea de prueba.

¿Qué debe tener en cuenta un equipo que integra desde China?

Confirma primero la accesibilidad de la red, la transferencia de datos al exterior y el cumplimiento de contenido; después evalúa los términos del proveedor y el riesgo de suspensión. Si necesitas un acceso unificado, puedes registrarte en ZSQH AI Gateway y revisar en la página de precios de modelos los modelos disponibles; no trates una interfaz de imágenes que no sigue el protocolo OpenAI como si fuera compatible.

Siguientes pasos

Primero completa las cuatro etapas —enviar, consultar, descargar y almacenar— con un prompt de baja complejidad; después añade ampliaciones, variaciones y callbacks. Al elegir proveedor, pon el cumplimiento y el mecanismo de salida por delante de la calidad de las imágenes. Si necesitas administrar varios modelos desde un solo punto de acceso, regístrate en ZSQH AI Gateway y confirma en la página de precios de modelos los modelos y la facturación disponibles.

Lecturas relacionadas: