Midjourney

Midjourney es una API asíncrona: envíe una tarea para obtener un ID de tarea de HopBase y consúltelo hasta tener el resultado; cada tarea devuelve exactamente cuatro imágenes y todas se facturan.

Modelos disponibles

Confirme el ID exacto de modelo disponible para su clave con GET /v1/models antes de enviar trabajo de pago.

Parámetros de la solicitud

Todas las solicitudes usan Authorization: Bearer sk-su-clave y Content-Type: application/json. El tamaño y la calidad van en parámetros -- al final del prompt, no en campos de la solicitud.

Campos del cuerpo

• prompt debe incluir una descripción, no solo parámetros --, y no puede contener ::; las imágenes sin descripción se rechazan.
• images es una imagen de referencia, por ejemplo [{"url":"https://example.com/ref.png"}]. Admite una sola imagen; para varias, vea «Varias imágenes de referencia» más abajo.
• Cada elemento de images[] lleva exactamente uno de url (HTTP(S) absoluta y pública) o file_id, y no lleva usage.
• Un quality no vacío devuelve 400; para 2K use --hd en el prompt.
• Un objeto extra no vacío devuelve 400; este modelo no acepta parámetros adicionales.

Los campos que suelen enviar los clientes de OpenAI Images, como size, response_format y style, están fuera de la tabla; la lista completa está en «Más detalles», dentro de Advertencias.

Tamaño y relación de aspecto

El tamaño de la imagen viene de --ar (o su alias --aspect) en el prompt. --hd genera de forma nativa aproximadamente al doble de longitud de lado.

Sirve cualquier relación de números enteros, no solo las de la tabla, siempre que ninguna dirección supere 14:1 (4:1 con --hd). La tabla recoge las relaciones más habituales; todos los tamaños están medidos, no derivados: --hd no es una duplicación exacta.

• --ar lleva exactamente un valor ancho:alto formado por enteros positivos; --ar 1.5:1 se rechaza.
• La relación no puede superar 14:1 en ninguna de las dos direcciones.
• --hd baja ese techo a 4:1: --hd --ar 14:1 se rechaza, mientras que --hd --ar 4:1 se genera a 4096 × 1184.

Parámetros del prompt

Estos se aceptan y se transmiten:

• Escriba todos los parámetros después de la descripción: el texto que sigue al primer parámetro -- se lee como valor de ese parámetro.
• Un parámetro numérico con rango debe ir seguido de exactamente un número; si falta el valor, hay varios, no es un número o está fuera de rango, se devuelve 400.

Varias imágenes de referencia

images admite una sola imagen. Para usar varias, ponga sus URL al principio de prompt, separadas por espacios, y después la descripción; es la sintaxis estándar de Image Prompt de Midjourney:

"prompt": "https://example.com/a.png https://example.com/b.png a cat sitting in a vintage car --ar 1:1"

• Cada URL debe ser una dirección HTTP(S) pública.
• Las imágenes de referencia son inspiración, no un collage: su influencia no se reparte por igual, y un sujeto muy marcado en una imagen puede imponerse al resto.
• Para asegurarse de que aparezca algo de una imagen concreta, nómbrelo en la descripción o suba --iw (0-3) para dar más peso a las imágenes de referencia.

Parámetros rechazados

Estos se rechazan con 400 en el envío. De lo contrario, el modelo los ignoraría en silencio —y usted pagaría por un efecto que nunca obtuvo— o haría fallar la tarea minutos después.

Respuesta

Respuesta del envío

Un envío exitoso devuelve HTTP 202:

{
  "id": "ktEXAMPLE",
  "object": "image.generation.task",
  "model": "midjourney-v8-2",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "img_1k",
  "requested_images": 4,
  "images_per_task": 4,
  "notice": "this model always returns 4 images per task and bills every returned image"
}

Resultado de la consulta

status pasa por queued → processing → completed o failed. Solo estos dos últimos son terminales, así que trate cualquier otro valor como en curso.

Extracto de una tarea completada; el ID y las URL son de ejemplo:

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "midjourney-v8-2",
  "status": "completed",
  "created": 1790000000,
  "outputs": [
    "https://api.hop-base.com/example-signed-image-1.png",
    "https://api.hop-base.com/example-signed-image-2.png",
    "https://api.hop-base.com/example-signed-image-3.png",
    "https://api.hop-base.com/example-signed-image-4.png"
  ],
  "usage": { "bucket": "img_1k", "billed_images": 4, "cost": 0.1496, "cost_usd": 0.022, "currency": "CNY" }
}

Las URL de salida se sirven desde api.hop-base.com como enlaces firmados válidos por 24 horas desde que la tarea se completa. Consultar de nuevo devuelve la misma URL sin extenderla, y un enlace vencido devuelve 410, así que descargue las imágenes a tiempo.

Cuando la tarea termina, el objeto usage de la raíz de la consulta también incluye cost_usd —el importe en USD realmente descontado de su saldo por esta tarea, 0 si falló sin cargo—, cost (el mismo cargo en CNY) y currency (siempre CNY); consulte Generación de video. En la lista de tareas (GET /v1/video/tasks), cada tarea finalizada lleva los mismos cost, cost_usd y currency en su usage.

Ejemplos

Envíe una tarea 16:9 y consúltela hasta un estado terminal:

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-su-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-v8-2",
    "prompt": "a red apple on a wooden table, studio light --ar 16:9"
  }'

# Consulte con el id devuelto; sin encabezado de facturación
curl https://api.hop-base.com/v1/video/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-su-clave"

Advertencias

• Cada tarea devuelve cuatro imágenes y todas se facturan, así que presupueste cuatro imágenes por envío.
• n solo acepta 4 o nada en absoluto.
• Indique la relación con --ar y el 2K con --hd; size o quality en el cuerpo devuelven 400.
• Con --hd, el techo de la relación de aspecto baja de 14:1 a 4:1.
• Escriba todos los parámetros -- después de la descripción.
• La concurrencia es limitada: enviar un lote grande en paralelo hace fallar la mayoría en lugar de ponerlo en cola.
• Una tarea que sigue sin terminar 2 horas después de crearse se marca como fallida y no se factura.

Errores comunes

Todos los errores del envío son HTTP 400; no se crea ninguna tarea y no se factura nada. Las comprobaciones se hacen en orden y se devuelve el primer fallo, con este cuerpo:

{
  "error": {
    "message": "request body does not match the JSON contract: json: unknown field \"size\"",
    "type": "invalid_request_error"
  }
}

Tareas fallidas

Una tarea fallida sigue respondiendo a la consulta con HTTP 200 y status failed. Decida el éxito o el fallo por status, ramifique su lógica por error.code y muestre error.message.

# Un campo fuera de la tabla
request body does not match the JSON contract: json: unknown field "<campo>"

# quality no vacío
the quality field has no effect on this model; ask for 2K output with --hd in the prompt instead

# n distinto de 4
this model always returns 4 images per task and bills every returned image; the n field cannot change that, so omit it or set it to 4

# prompt vacío
prompt is required for this model, even when input images are provided

# :: en el prompt
multi-prompt weighting (::) is not supported on this model version

# Parámetros sin descripción
prompt must contain a description, not only parameters

# Un parámetro rechazado
parameter --<nombre> is not accepted: <motivo>

# Un elemento de images[] sin url / file_id o con ambos
images[<índice>] must provide exactly one of url or file_id

# url que no es una dirección http(s) pública y absoluta
images[<índice>].url must be a publicly accessible absolute http(s) URL

# usage en un elemento de images[]
images[<índice>].usage is not part of the image generation API; remove this field

# extra no vacío
model "midjourney-v8-2" does not accept unverified extra parameters

# Más de una imagen de referencia
model "midjourney-v8-2" accepts at most 1 input images, got <cantidad>

# --ar sin valor o con varios
parameter --ar requires exactly one value such as 16:9

# --ar sin la forma ancho:alto
parameter --ar must look like 16:9, got "<valor>"

# Decimales en --ar
parameter --ar must use whole numbers such as 3:2; decimals are rejected, got "<valor>"

# Cero o negativos en --ar
parameter --ar must use positive numbers, got "<valor>"

# Relación mayor que 14:1
parameter --ar may not exceed 14:1, got "<valor>"

# Relación mayor que 4:1 con --hd
parameter --ar may not exceed 4:1 when --hd is used, got "<valor>"

# Parámetro numérico sin valor o con varios
parameter --<nombre> requires exactly one numeric value

# Parámetro numérico que no es un número
parameter --<nombre> must be a number, got "<valor>"

# Parámetro numérico fuera de rango
parameter --<nombre> must be between <mín> and <máx>, got <valor>

{
  "id": "ktEXAMPLE",
  "object": "video.generation.task",
  "model": "midjourney-v8-2",
  "status": "failed",
  "created": 1790000000,
  "error": {
    "code": "input_sensitive",
    "message": "the prompt was rejected by content moderation; rephrase it and submit again"
  }
}

# input_sensitive: la moderación de contenido rechazó el prompt
the prompt was rejected by content moderation; rephrase it and submit again

# input_sensitive: la moderación de contenido rechazó la imagen de referencia
the reference image was rejected by content moderation; replace it and submit again

# input_sensitive: la moderación de contenido lo rechazó sin indicar el origen
the prompt or reference image was rejected by content moderation; revise it and submit again

# rate_limited: techo de concurrencia alcanzado
this model is at its concurrency limit right now; please retry shortly

# prompt_required: falta la descripción
prompt is required for this model, even when input images are provided

# invalid_request: parámetro no admitido
the prompt uses a parameter that this model version does not support

# invalid_request: relación de aspecto no válida
the --ar value is not a valid aspect ratio for this model

# invalid_request: prompt mal formado
the prompt was rejected by the model; check the parameters at the end of the prompt

# generation_failed: fallo de generación (otros)
image generation failed; please retry, and contact support with the task ID if it keeps failing

# generation_failed: no se pudo seguir la tarea (termina así)
… contact support with the task ID

# timeout: tiempo agotado
task did not reach a billable terminal state within 2 hours; polling stopped

# no_output: terminó sin salida
image generation finished without a usable output; please retry, and contact support with the task ID if it keeps failing

Facturación

Midjourney factura por imagen devuelta, así que una tarea cuesta cuatro imágenes a la tarifa de su nivel; el render predeterminado y el render 2K con --hd tienen precios distintos. Solo se factura una tarea completada correctamente; los envíos rechazados, los rechazos de moderación y las tareas fallidas no se facturan.

Los precios de lista oficiales están en la página de precios. Su tarifa es la que aparece en el catálogo de modelos con la sesión iniciada, y el cargo real de cada solicitud está en su registro de uso.

Las especificaciones y los precios oficiales del modelo también están en su ficha del modelo.

Próximos pasos

• Resumen de generación de imágenes: todas las series de modelos de imagen y sus reglas comunes
• Imágenes de Kling: otra serie de imagen que funciona con tareas asíncronas
• Referencia de API: crear imagen: todos los campos del cuerpo
• Referencia de API: consultar tarea de video: el endpoint de consulta de las tareas de Midjourney
• Estudio creativo: genere imágenes y video sin escribir código
• Solución de problemas: busque un mensaje de error