Cómo usar imagen-4.0-ultra a través de la API de HiAPI: curl, Python y ejemplos de solicitud ejecutables

Qué es imagen-4.0-ultra y cuándo elegirlo

imagen-4.0-ultra es el nivel de mayor fidelidad de la familia imagen-4.0, y HiAPI lo expone como modelo de generación de imágenes en el mismo endpoint compatible con OpenAI que las series de chat y otros modelos. El modelo mental es sencillo: envías un cuerpo de solicitud JSON estructurado que describe una imagen y recibes datos de imagen, no un resultado de chat completion.

Elegir entre niveles depende principalmente de la tarea, no de un ranking:

• Borradores e iteración. Si estás explorando prompts, probando composiciones o generando miniaturas para decidir una dirección, los modelos de imagen más ligeros responden más rápido y cuestan menos por generación. Reserva ultra para la ronda que realmente importa.
• Material final. Las imágenes principales, los visuales de marketing y cualquier contenido que las personas vayan a examinar a tamaño original se benefician del nivel ultra en detalle, adherencia al prompt y capacidad de manejar escenas complejas con múltiples sujetos o elementos similares a texto.
• Pipelines por lotes con umbral de calidad. Un patrón común es generar borradores ampliamente con un modelo ligero y luego volver a ejecutar solo los prompts seleccionados en imagen-4.0-ultra. Como HiAPI coloca el ID del modelo en el cuerpo de la solicitud, cambiar de nivel es solo cambiar una cadena, no hacer una nueva integración.

Hay algunas expectativas que conviene fijar de antemano. La generación de imágenes no es instantánea; una sola solicitud a ultra puede tardar notablemente más que un chat completion, así que diseña el cliente con tiempos de espera amplios y no asumas latencia inferior al segundo. Y como la respuesta transporta datos binarios de imagen en lugar de un arreglo choices, cualquier código de análisis escrito para modelos de chat no sirve; planifícalo desde el principio.

Si no estás seguro de si necesitas ultra, envía primero una solicitud mínima, revisa la salida a la resolución con la que realmente planeas entregar y luego compárala con niveles más ligeros. Juzgar la calidad de imagen a partir de una vista previa reducida resulta engañoso.

Requisitos previos y configuración de autenticación

Antes de enviar la primera solicitud, confirma tres cosas: tienes una clave de API de HiAPI, conoces la URL base del endpoint compatible con OpenAI y tu herramienta puede hacer solicitudes HTTPS (curl, o Python con requests, incluso httpx).

Mantén la clave fuera de tu código

Guarda la clave en una variable de entorno en lugar de pegarla en el script:

export HIAPI_API_KEY="your_api_key_here"

En producción, usa el gestor de secretos de tu plataforma e inyecta el valor en tiempo de ejecución. Confirmar la clave en un repositorio de código es la forma más común de filtrar credenciales, y rotar una clave es mucho más doloroso que leerla desde una variable de entorno.

Encabezados de autenticación

Cada solicitud lleva el encabezado estándar de token Bearer:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Ambos encabezados importan. La ausencia de Content-Type puede hacer que el servidor rechace o analice mal el cuerpo de la solicitud, lo que a veces se manifiesta como un error genérico confuso en lugar de un mensaje de validación claro.

La misma clave y el mismo patrón de encabezados aplican en todas las series de modelos de HiAPI, y ese es el beneficio práctico del endpoint unificado: una credencial, un cliente, múltiples modelos.

Verificación rápida de estado

Si tienes a mano un ID de modelo compatible con chat, enviar primero una solicitud de texto simple es una forma económica de confirmar que la clave y los encabezados son correctos antes de depurar el cuerpo de una solicitud de imagen. Separar los problemas de autenticación de los del cuerpo ahorra tiempo de verdad. Si la solicitud de texto funciona y la de imagen falla, sabes que el problema está en el cuerpo de la solicitud de imagen.

Construir el cuerpo de la solicitud

Empieza por el cuerpo mínimo que puede generar una imagen: ID del modelo más un prompt. Todo lo demás es optimización opcional.

{
  "model": "imagen-4.0-ultra",
  "prompt": "A sunlit reading room with tall windows, a wooden desk, and shelves of worn books, soft dust motes in the light"
}

Dos principios lo mantienen mantenible. Primero, el ID del modelo debe coincidir exactamente con el que HiAPI documenta para este modelo: sin espacios, sin sufijos de versión inventados por ti. Segundo, el prompt es lenguaje natural puro; escríbelo como le describirías una imagen a un fotógrafo, prefiriendo sustantivos concretos y pistas de iluminación o composición en lugar de adjetivos abstractos.

Formas de prompt que suelen funcionar

• Primero el sujeto, luego la escena, luego el estilo. "A fox in a snowy birch forest, morning light, shallow depth of field" es más fiable que una pila de palabras clave de estilo.
• Sé específico sobre la composición. Menciona el ángulo de cámara, el encuadre o la disposición cuando importen para tu caso de uso.
• Evita contradicciones. Pedir "minimalista" y "detalles ornamentales intrincados" en la misma frase suele producir un compromiso que no querías.

Tamaño y relación de aspecto

Los modelos de imagen suelen aceptar opciones de ancho/alto o relación de aspecto, pero los nombres exactos de los parámetros y los valores admitidos varían según el modelo. No adivines: consulta la documentación de parámetros de ese modelo en HiAPI y usa solo los valores que allí se enumeran. Si pasas un tamaño o proporción que el modelo no admite, espera un error de validación, no un fallback silencioso.

El flujo de trabajo seguro es: empezar con los valores predeterminados, confirmar una respuesta exitosa y luego añadir un parámetro de tamaño a la vez y comprobar la salida. Si después de añadir un parámetro las solicitudes empiezan a fallar, has localizado la causa en el último cambio.

No incluyas ningún parámetro opcional en la primera solicitud. Un cuerpo que funciona con solo dos campos es una base mejor que un cuerpo que falla con diez campos.

Una solicitud curl ejecutable

Después de exportar la clave, esta es la forma de solicitud que puedes copiar y adaptar:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "prompt": "A sunlit reading room with tall windows, a wooden desk, and shelves of worn books, soft dust motes in the light"
  }'

Qué hace cada parte:

• -X POST: la generación de imágenes es una operación de creación, no de lectura.
• URL: la ruta de generación de imágenes en el endpoint compatible con OpenAI de HiAPI. Configura HIAPI_BASE_URL con la URL base que muestra la documentación de HiAPI, para que la ruta siga siendo correcta aunque cambie el host.
• Los dos encabezados: autenticación Bearer y tipo de contenido JSON, como se describió arriba.
• Cuerpo -d: el mismo JSON que reutilizarás en Python. Las comillas importan: envuelve la carga útil en comillas simples para evitar que el shell expanda nada de su contenido.

Consejos de depuración

Añade -i para incluir los encabezados de respuesta, de modo que puedas ver el estado HTTP aunque el cuerpo sea grande. Si quieres confirmar qué se envió realmente, añade -v y lee la línea de solicitud emitida: expone rápidamente URLs mal formadas o encabezados faltantes.

Si la salida en la terminal es una gran masa de base64 o ruido binario, la solicitud tuvo éxito. No la canalices a los logs; consulta la sección de manejo de respuestas para una forma más limpia. Redirigir la respuesta sin procesar a un archivo (> out.json) es aceptable para una comprobación puntual.

Una vez que curl devuelve un estado exitoso y un cuerpo analizable, tienes un contrato verificado. El paso en Python debería reproducir ese JSON exacto byte a byte (estructuralmente), de modo que cualquier fallo posterior sea atribuible al código y no a una solicitud distinta.

La misma solicitud en Python

Con requests, la llamada equivalente se mantiene cerca de la versión curl, lo que facilita la verificación cruzada:

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "imagen-4.0-ultra",
    "prompt": (
        "A sunlit reading room with tall windows, a wooden desk, "
        "and shelves of worn books, soft dust motes in the light"
    ),
}

response = requests.post(
    f"{base_url}/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()

Algunas notas importantes en la práctica:

• json=payload serializa el diccionario y establece el tipo de contenido por ti. Aun así, puedes pasar los encabezados explícitamente por claridad o para mantener la coherencia con curl.
• timeout=120 no es decorativo. La generación de imágenes puede ser lenta; sin un tiempo de espera explícito, heredas el valor predeterminado de la biblioteca, que puede ser más corto de lo que esperas, y una interrupción del cliente parece un fallo del servidor.
• raise_for_status() convierte las respuestas 4xx y 5xx en excepciones, en lugar de dejar que un cuerpo de error mal formado fluya hacia tu código de análisis.

Encapsular para reutilizar

Coloca la llamada en una función pequeña que acepte el prompt y parámetros opcionales, devuelva el resultado analizado y registre solo el ID del modelo, la longitud del prompt, el código de estado y el tiempo transcurrido. Esa línea de log basta para depurar la mayoría de los problemas sin almacenar megabytes de datos de imagen en el agregador de logs.

Como el cuerpo de la solicitud es JSON puro, la misma función sirve para otros modelos de imagen de HiAPI: sustituye el ID del modelo y, si hace falta, los parámetros de tamaño admitidos. Conserva algunos prompts de ejemplo en el script de pruebas, para que tras cualquier actualización del cliente puedas volver a ejecutar una solicitud que sabes que funciona y obtener una señal rápida.

Manejar la respuesta de imagen

La respuesta es una carga útil de imagen, no un chat completion. No busques choices[0].message.content: escribe código de análisis que coincida con lo que realmente devuelve la ruta de imagen, según la documentación de HiAPI.

Análisis defensivo

La respuesta suele transportar los datos de imagen como una cadena base64, a veces acompañada de metadatos. Decodifica solo después de confirmar que el campo existe:

import base64

item = result["data"][0]
image_b64 = item.get("b64_json")
if image_b64 is None:
    # 某些响应可能携带 URL 或其他格式；请查阅文档
    raise ValueError(f"Unexpected image payload keys: {list(item)}")

image_bytes = base64.b64decode(image_b64)
with open("output.png", "wb") as f:
    f.write(image_bytes)

list(item) en el mensaje de error es la parte útil: cuando cambia la carga útil, te dice las claves reales en lugar de hacerte adivinar.

Registrar en logs sin volcar binarios

Nunca registres el cuerpo sin procesar de una solicitud de imagen: es enorme y en su mayoría ilegible. Registra el código de estado, la longitud del contenido, el ID del modelo y el hash o el número de bytes de la imagen decodificada. Eso basta para verificar que cada prompt produjo una imagen distinta sin inflar el almacenamiento.

Hábitos operativos

• Valida antes de almacenar. Confirma que los bytes decodificados comienzan con una firma de imagen reconocible y captura los errores de decodificación donde escribas el archivo.
• Escrituras atómicas. Guarda en una ruta temporal y renombra tras el éxito, para que un fallo a mitad de escritura no deje un archivo truncado que parezca válido.
• Guarda el prompt junto con la salida. Conserva junto a cada imagen el prompt, el ID del modelo y cualquier parámetro de tamaño. Cuando más adelante las partes interesadas pidan variantes, necesitarás la solicitud original.
• Establece reglas de retención. Las imágenes generadas se acumulan; decide desde el principio dónde se guardan y cuánto tiempo se conservan.

Diagnosticar solicitudes fallidas

La mayoría de los fallos en la primera solicitud encajan en tres categorías. Revísalas en este orden antes de tocar el prompt.

Fallo de autenticación

Un 401 o 403 casi siempre significa que el encabezado está mal. Verifica que el esquema sea exactamente Bearer, seguido de un espacio y la clave, sin espacios finales ni comillas sobrantes. Confirma que la variable de entorno está realmente definida en el shell o proceso donde ejecutas la solicitud: una clave exportada en una terminal no existe en otra. Si rotaste la clave recientemente, asegúrate de que el valor antiguo no siga en caché en un archivo de configuración o en un secreto de despliegue.

ID de modelo incorrecto

Una respuesta de modelo no encontrado significa que el campo model no coincide con el ID registrado en HiAPI. Copia el identificador de la documentación de modelos de HiAPI en lugar de volver a escribirlo; un carácter equivocado o un sufijo de versión inventado basta para fallar. Si cambias el ID del modelo para comparar niveles, comprueba que el reemplazo esté en el cuerpo de la solicitud y no solo en un comentario.

Parámetros rechazados

Un error de validación que señala un campo suele significar un tamaño o relación de aspecto no admitidos, o un parámetro opcional que el modelo no acepta. Elimina todos los campos opcionales, confirma que la solicitud mínima de dos campos funciona y luego vuelve a añadir los parámetros uno a uno. Eso aísla el problema de inmediato.

Otros síntomas

• 200 pero cuerpo vacío o no analizable: puede que estés leyendo el campo equivocado. Revisa las claves de nivel superior antes de indexar dentro de la carga útil.
• Tiempo de espera del cliente agotado pero el servidor ya facturó: tu tiempo de espera puede ser demasiado corto; auméntalo y reintenta una vez con el mismo prompt antes de darlo por fallido.
• JSON distinto en curl y en Python: imprime la carga útil serializada en Python y compárala con la cadena -d de curl. Esta diferencia explica la mayoría de los informes de "funciona en curl".

Si los revisas en orden, resolverás la gran mayoría de los problemas de primera integración sin cambiar una sola palabra del prompt. Después, tras cada actualización del cliente o del SDK, ejecuta un prompt que sabes que funciona con un pequeño script de pruebas para detectar regresiones a tiempo.