API de imágenes

HopBase presenta a los clientes un único protocolo compatible con OpenAI Images. Envíe las solicitudes de texto a imagen a POST https://api.hop-base.com/v1/images/generations. Incluso para Gemini Banana, no envíe un payload nativo de Gemini generateContent; HopBase adapta la solicitud según el modelo seleccionado.

Endpoints

Método	Ruta	Propósito	Formato de solicitud
POST	`/v1/images/generations`	Texto a imagen; Seedream también acepta `image` para transformación y edición	`application/json`
POST	`/v1/images/edits`	Imagen a imagen y edición	`multipart/form-data` (recomendado), o JSON con URLs / Data URLs
GET	`/v1/images/tasks?task_id=...`	Consultar una tarea asíncrona	Se usa después de una solicitud con `Prefer: respond-async`

Todos los endpoints usan Authorization: Bearer sk-tu-clave. La Base URL es https://api.hop-base.com/v1.

Solicitud curl mínima de texto a imagen

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Un Shiba Inu sentado bajo flores de cerezo, estilo acuarela japonesa",
    "size": "2048x2048",
    "quality": "medium",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'

Texto a imagen con el SDK de Python de OpenAI

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hop-base.com/v1",
    api_key="sk-tu-clave",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="Un Shiba Inu sentado bajo flores de cerezo, estilo acuarela japonesa",
    size="2048x2048",
    quality="medium",
    background="opaque",
    output_format="png",
    n=1,
)

image = resp.data[0]
with open("result.png", "wb") as f:
    f.write(base64.b64decode(image.b64_json))

Compatibilidad con Gemini Banana

Capacidad	Comportamiento de Gemini a través de HopBase
Endpoint de solicitud	Los clientes siempre llaman a `/v1/images/generations`; HopBase adapta la solicitud según el modelo seleccionado.
Respuesta	Los resultados usan el JSON de OpenAI Images, normalmente en `data[].b64_json` y a veces en `data[].url`.
Imagen a imagen	Los modelos de Gemini que admiten edición aceptan una o más referencias y una instrucción en lenguaje natural a través de `/v1/images/edits`. Gemini no ofrece restricciones de región duras mediante `mask`.
Tamaño	HopBase valida `size` según el modelo y lo adapta cuando es necesario.
Otros parámetros	El soporte de `quality`, `background`, `output_format`, `input_fidelity` y `n` depende del modelo. No asuma paridad exacta con GPT Image.
Streaming	Use el modo síncrono para las imágenes de Gemini. No envíe `"stream": true`; los modelos no compatibles devuelven un error explícito.
Asíncrono	Algunos modelos admiten `Prefer: respond-async`. Use el código de estado HTTP real para determinar si el resultado es un `202 task_id`.

La adaptación de Gemini ocurre en el servidor de HopBase. La Base URL del cliente, la clave Bearer y la estructura de solicitud de OpenAI Images no cambian.

ID de modelo de imagen de Gemini Banana

Familia	ID de modelo	Tamaño
Banana	`gemini-2.5-flash-image`	1K
Banana Pro	`gemini-3-pro-image` / `gemini-3-pro-image-c` `gemini-3-pro-image-preview` / `gemini-3-pro-image-preview-c`	1K / 2K / 4K
Banana 2	`gemini-3.1-flash-image` / `gemini-3.1-flash-image-c` `gemini-3.1-flash-image-preview` / `gemini-3.1-flash-image-preview-c`	1K / 2K
Banana 2 Lite	`gemini-3.1-flash-lite-image`	1K

Las variantes -c son IDs de modelo de producción independientes con el mismo protocolo de cliente que el resto de su familia. No agregue ni quite el sufijo por su cuenta. Llame a GET /v1/models con la clave actual y use un ID completo devuelto.

Los modelos de imagen de Gemini se facturan por el consumo real de tokens. Los multiplicadores de conversión pueden variar según el grupo del plan; la Plaza de modelos tras iniciar sesión es la fuente autorizada.

Modelos Seedream disponibles

Modelo	ID de modelo	Tamaños	Salida / optimización	Precio de referencia
Seedream 5.0 Pro	`seedream-5-0-pro`	1K / 1.5K / 2K	PNG / JPEG; standard / fast	$0.045 por imagen a 2.36 MP o menos; $0.09 por encima de 2.36 MP
Seedream 5.0 Lite	`seedream-5-0-lite`	2K / 3K / 4K	PNG / JPEG; standard	$0.035 por imagen
Seedream 4.5	`seedream-4-5`	2K / 4K	JPEG; standard	$0.04 por imagen

Lite es el modelo ligero de Seedream 5.0. No trate seedream-5-0-lite como Pro. La tabla anterior muestra los precios de referencia oficiales; su precio efectivo sigue el multiplicador de su grupo y se muestra en la Plaza de modelos tras iniciar sesión. En Pro, 1.5K cuesta lo mismo que 1K con mejor calidad - prefiera 1.5K para salidas de tamaño pequeño a mediano. Lite y 4.5 tienen un mínimo de clase 2K (al menos 3,686,400 píxeles totales); use Pro cuando necesite salida en 1K.

Seedream 5.0 Pro texto a imagen

El texto a imagen de Seedream usa /v1/images/generations, se factura por imagen de salida y devuelve una URL firmada válida por 24 horas. El ejemplo usa Pro; puede seleccionar un ID de Lite o 4.5 devuelto para la clave actual y seguir los límites de parámetros de ese modelo.

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "Una calle futurista de ciudad de noche con luz de neón, composición cinematográfica",
    "size": "2048x2048",
    "response_format": "url"
  }'

Seedream 5.0 Pro imagen a imagen y edición (se recomienda JSON)

Siga llamando a /v1/images/generations y agregue image. Acepta de 1 a 10 URLs HTTP(S) o Data URLs de imagen. La transformación de una sola imagen, la composición de varias imágenes, el redibujado de referencias y las ediciones locales marcadas con coordenadas, cuadros delimitadores, flechas o trazos de pintura usan todos este endpoint.

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "Mueva la taza de la primera imagen al lado derecho de la mesa y mantenga todo lo demás sin cambios",
    "image": ["https://example.com/source.png"],
    "size": "2K",
    "output_format": "png",
    "response_format": "url"
  }'

Seedream 5.0 Pro a través de OpenAI edits (archivos locales)

El código de edición existente de OpenAI Images puede usar solicitudes multipart a /v1/images/edits. HopBase adapta los archivos y el formato de solicitud.

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-tu-clave" \
  -F "model=seedream-5-0-pro" \
  -F "prompt=Rediseñe el póster a partir de ambas referencias conservando el sujeto y los colores de marca" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "size=2K" \
  -F "output_format=png"

Parámetros comunes de Seedream

Campo	Descripción
`model`	Un ID completo de Seedream devuelto por `GET /v1/models` de la clave actual
`prompt`	Contenido, composición, estilo o instrucción de edición. Las ediciones locales pueden describir coordenadas, un cuadro delimitador, flechas o regiones pintadas en una referencia.
`image`	URL / Data URL única opcional o un arreglo. Límites: 10 para Pro, 14 para Lite y 4.5. Al proporcionarla se habilita la transformación y edición de una o varias imágenes.
`size`	Use un tamaño abreviado de la tabla. Los valores personalizados `ANCHOxALTO` necesitan una relación de aspecto de 1:16 a 16:1. Rango de píxeles totales: 921,600-4,624,220 para Pro; 3,686,400-16,777,216 para Lite y 4.5 (los valores por debajo del mínimo se rechazan en el gateway con el rango válido).
`output_format`	Pro / Lite: `png` o `jpeg`; 4.5: solo `jpeg`
`optimize_prompt_options.mode`	Pro: `standard` o `fast`; Lite / 4.5: solo `standard`
`response_format`	HopBase usa actualmente `url` y devuelve un enlace directo a la imagen.

Los multiplicadores y cargos específicos de la cuenta se muestran en la Plaza de modelos tras iniciar sesión. Seedream admite texto a imagen síncrono, una o varias referencias y edición con n=1 y response_format=url. No admite tareas de imagen asíncronas ni streaming. Cada entrada puede ser de hasta 30 MB / 36 MP en formato JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC o HEIF. Las URLs firmadas devueltas son válidas por 24 horas; descárguelas con prontitud.

La edición local de Seedream no usa una máscara dura tradicional. Dibuje la anotación directamente sobre una imagen de referencia y describa su coordenada, cuadro delimitador, flecha o región pintada en el prompt. Pasar mask a /v1/images/edits devuelve 400 para evitar un comportamiento ambiguo.

Use una clave de grupo del plan para la cual GET /v1/models devuelva el ID completo de Seedream objetivo. No asuma que otro grupo del plan puede llamar a estos modelos.

Imagen a imagen o edición genérica con curl multipart

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-tu-clave" \
  -F "model=gpt-image-2" \
  -F "prompt=Convierta la referencia en una pintura al óleo estilo Van Gogh de una noche estrellada" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

Campos comunes de solicitud

Campo	Requerido	Descripción
`model`	Sí	`gpt-image-2`, o un ID completo de imagen de Gemini Banana / Seedream devuelto por `GET /v1/models` de la clave actual
`prompt`	Sí	Contenido, composición, estilo y requisitos de texto de la imagen
`size`	No	`auto` o `WIDTHxHEIGHT`; los valores comunes incluyen 1024x1024, 1536x1024, 1024x1536 y 2048x2048
`quality`	No	`low`, `medium`, `high` o `auto`
`n`	No	Número de imágenes; algunos modelos solo admiten 1
`background`	No	`opaque` o `transparent`
`output_format`	No	`png`, `jpeg` o `webp`
`image` / `mask`	Image es obligatorio para edición; mask depende del modelo	`/images/edits` acepta una o más referencias para los modelos compatibles. Gemini no acepta `mask`. Seedream acepta hasta 10 imágenes de referencia para Pro (14 para Lite y 4.5) de 30 MB cada una y tampoco acepta una `mask` tradicional.

Los tamaños de imagen se validan contra el modelo seleccionado. Los tamaños 2K o 4K no compatibles devuelven 400 antes de la generación y no generan cargo por imagen.

Respuesta síncrona (predeterminada)

Sin un encabezado Prefer, la solicitud espera a que se complete y devuelve el JSON estándar de OpenAI Images. La imagen suele estar en data[].b64_json; algunos modelos devuelven data[].url. usage contiene el consumo de tokens.

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

Los modelos de imagen que no son de Gemini y admiten streaming cambian a SSE cuando está presente "stream": true. El stream envía pings de keepalive; el último evento data: contiene el JSON de Images y va seguido de [DONE]. Los modelos de imagen de Gemini no admiten este comportamiento SSE de Images. Mantenga el modo síncrono predeterminado con los SDKs oficiales.

Modo de tarea asíncrona (gateways de OpenAI / Gemini Images)

Con el encabezado Prefer: respond-async, los modelos compatibles devuelven de inmediato 202 Accepted, un task_id y una status_url. Haga polling hasta que la tarea esté pending, processing, completed o failed. Al completarse, result_content contiene una URL en Markdown para la imagen almacenada. Los modelos de imagen de Gemini también admiten tareas asíncronas; prefiera este modo para imágenes 2K / 4K para evitar que solicitudes de larga duración sean cortadas por los tiempos de espera del CDN.

# 1. Enviar y recibir 202 + task_id
curl -i https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Una ciudad futurista cinematográfica de noche",
    "size": "2048x2048"
  }'

# 2. Hacer polling con el task_id de la primera respuesta
curl "https://api.hop-base.com/v1/images/tasks?task_id=tu-task-id" \
  -H "Authorization: Bearer sk-tu-clave"

En esta página