Cómo usar gpt-image-2-beta a través de la API de hiapi: parámetros, código y ejemplos ejecutables

gpt-image-2-beta es la ruta minimalista y de precio fijo para acceder a GPT Image 2 en hiapi: dos campos de entrada, un precio, sin ajustes de relación de aspecto ni de calidad. Esta guía muestra el ejemplo mínimo ejecutable, la estructura exacta de parámetros (confirmada mediante la exploración del endpoint en producción), y cómo se compara con la ruta predeterminada gpt-image-2/text-to-image, para que puedas decidir cuándo usar cada una.

Requisitos previos

Necesitas obtener una clave de API desde la página de API Keys del panel de hiapi; la clave comienza con sk-. El precio actual por imagen individual se puede consultar en la página del modelo gpt-image-2-beta y en la página de precios.

Como todos los modelos de imagen en hiapi, este modelo funciona sobre el endpoint unificado de tareas asíncronas:

• POST https://api.hiapi.ai/v1/tasks — crea una tarea de generación
• GET https://api.hiapi.ai/v1/tasks/{taskId} — consulta el estado de la tarea

En qué se diferencia la ruta beta

gpt-image-2/text-to-image (la ruta predeterminada) acepta aspect_ratio + resolution y se factura según el nivel de resolución ($0.03 para 1K, hasta $0.06 para 4K). gpt-image-2-beta reduce todo esto a un precio fijo único de $0.02 por imagen y un campo opcional size: una cadena de dimensiones en píxeles literales, como "1024x1024" o "1600x900", no una proporción. Si se omite size por completo, el modelo recurre a su tamaño de salida predeterminado.

El coste: renuncias al control granular de proporción/resolución a cambio de un precio más bajo y más simple. Es adecuado cuando solo necesitas «generar una imagen de forma económica» sin preocuparte por la composición exacta.

Ejemplo mínimo ejecutable (curl)

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

La imagen completada se encuentra en data.output[0].url. Esa URL tiene una vigencia corta mediante expireAt; descárgala de inmediato y vuelve a alojarla en tu propio almacenamiento; no la enlaces directamente en contenido de producción.

Imagen de ejemplo generada por la llamada curl anterior (con un prompt diferente), usando size: "1024x1024".

Python: crear + consultar + guardar en disco

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

Referencia de parámetros

El objeto input de gpt-image-2-beta solo acepta dos campos; la estructura es additionalProperties: false, por lo que cualquier otro contenido se rechaza directamente en lugar de ignorarse silenciosamente.

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	Descripción textual de la imagen que se va a generar.
size	string	No	Dimensiones en píxeles literales, por ejemplo "1024x1024", "1600x900". No es una palabra clave de relación de aspecto. Si se omite, se usa el tamaño de salida predeterminado del modelo.

Contenido no admitido (y los errores que obtendrás)

La estructura beta no acepta ningún campo que use la ruta predeterminada gpt-image-2/text-to-image ni la API de OpenAI Images: aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user o style. Enviar cualquiera de ellos devuelve inmediatamente un HTTP 400, por ejemplo:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

Si vas a migrar código desde la ruta predeterminada o desde la API de OpenAI Images, primero redúcelo a prompt + size y luego apunta a gpt-image-2-beta.

Precios: beta vs predeterminada vs @ext

Ruta	Precio	Controles
gpt-image-2-beta	$0.02/imagen fijo	Solo size (dimensiones en píxeles)
gpt-image-2/text-to-image (predeterminada)	$0.03 (1K) / $0.04 (2K) / $0.06 (4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	$0.007–$0.76, según calidad × resolución	16 relaciones de aspecto, niveles de calidad

Antes de decidir la ruta en producción, consulta la página de precios: el precio de cualquier modelo puede cambiar.

Consejos para construir sobre la ruta beta

• Considera la lista de campos anterior como la convención actual, no como una convención permanente. La estructura o los precios de la ruta beta tienen más probabilidades de ajustarse que los de la ruta predeterminada; si dependes de ella en producción, vuelve a consultar periódicamente la página del modelo.
• Como size es opcional, si tu diseño depende de unas dimensiones específicas, pásalo siempre explícitamente; no confíes en que el valor predeterminado actual se mantenga igual.
• Trata status: "fail" como con cualquier otro modelo de imagen de hiapi: lee task.error.code / task.error.message y reintenta con retroceso exponencial, en lugar de asumir que cada fallo es transitorio.

Preguntas frecuentes

¿gpt-image-2-beta y gpt-image-2/text-to-image son el mismo modelo? En esencia es el mismo modelo GPT Image 2, pero la ruta de API es diferente: la ruta beta intercambia control de parámetros por un precio fijo más bajo.

¿Puedo solicitar una relación de aspecto específica? No directamente. Elige una cadena size que tenga la proporción ancho:alto que necesitas (por ejemplo, "1600x900" para 16:9), en lugar de usar la enumeración aspect_ratio.

¿Qué ocurre si no paso size en absoluto? La tarea seguirá teniendo éxito: el modelo usa su propio tamaño de salida predeterminado.

Lecturas relacionadas

Para la ruta completa con control explícito de relación de aspecto y resolución, consulta Cómo usar gpt-image-2/text-to-image a través de la API de hiapi. ¿Listo para probarlo tú mismo? Obtén una clave desde la página de API Keys y ejecuta el ejemplo curl anterior.