Imágenes

Helmcode sirve dos modelos de imagen por los endpoints de imagen compatibles con OpenAI, así que los SDK de OpenAI funcionan contra ellos cambiando la base URL: flux-2-klein (por defecto; texto a imagen e imagen a imagen con referencias) y qwen-image-2.1 (texto a imagen).

Generar

curl https://api.helmcode.com/v1/images/generations \
  -H "Authorization: Bearer $HELMCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "un faro al atardecer, larga exposición",
    "size": "1024x1024",
    "n": 1
  }'

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.helmcode.com/v1",
    api_key="sk-hke_your-key-here",
)

img = client.images.generate(
    model="flux-2-klein",
    prompt="un faro al atardecer, larga exposición",
    size="1024x1024",
)
print(img.data[0].url)

model es opcional: si lo omites resuelve a flux-2-klein.

modelo	texto→imagen	referencias / edición	rango de tamaño
`flux-2-klein`	sí	hasta 4 en `/v1/images/edits`	256–1536
`qwen-image-2.1`	sí	no	512–1280

El catálogo también se puede consultar: GET /v1/images/models con tu API key (o GET /api/images/models desde una sesión de consola) devuelve cada modelo de imagen con su flag supports_edits.

Editar

Manda una o varias imágenes de referencia como multipart y el modelo trabaja a partir de ellas. El campo es image, repetido (o image[]). Este endpoint es solo flux-2-klein: qwen-image-2.1 es texto a imagen y rechaza las imágenes de referencia con un 400:

curl https://api.helmcode.com/v1/images/edits \
  -H "Authorization: Bearer $HELMCODE_API_KEY" \
  -F image=@foto.png \
  -F prompt="la misma composición, de noche" \
  -F size=1024x1024

Solo se usan las 4 primeras imágenes de referencia. Mandar más no da error y nada te avisa: las de sobra se descartan antes de que la petición salga de aquí. mask sí se rechaza, con mask is not supported for this model.

Límites

Cuántas imágenes al mes incluye tu plan está en Rate limits. Lo que sigue es lo que puede pedir una petición.

Campo	Valor
`prompt`	obligatorio, hasta 4000 caracteres
`n`	de 1 a 4
`size`	`ANCHOxALTO` o `auto`. Por defecto `1024x1024`
— ancho y alto	entre 256 y 1536 cada uno
— divisibilidad	los dos múltiplos de 16
— relación de aspecto	entre 1:3 y 3:1
imágenes de referencia	se usan las 4 primeras en `/v1/images/edits`, el resto se descarta en silencio
`response_format`	`url` (por defecto) o `b64_json`
`stream`	no soportado
formato devuelto	JPEG

Una url va prefirmada y vale una hora; el propio enlace lleva su X-Amz-Expires=3600 por si lo quieres comprobar. Si necesitas conservar la imagen, descárgala dentro de esa ventana o pide b64_json y escribe tú los bytes.

Las reglas de tamaño se comprueban antes de generar nada, y los errores nombran la regla que has roto:

n must be between 1 and 4 for model 'flux-2-klein'.
size width and height must both be divisible by 16.
size width and height must each be between 256 and 1536 for model 'flux-2-klein'.
size aspect ratio must be between 1:3 and 3:1.

Más allá de los campos de OpenAI

Tres extras, que van por extra_body en los SDK de OpenAI o como campos normales en una petición cruda:

Campo	Qué hace
`seed`	fija la semilla de muestreo, un entero en 0..2147483647. El mismo prompt, tamaño y semilla devuelven una imagen idéntica byte a byte
`guidance`	cuánto se ciñe el modelo al prompt (solo `flux-2-klein`)
`enhance_prompt`	reescribe tu prompt con un modelo de lenguaje antes de generar. Apagado por defecto en la API

Problemas conocidos

Los modelos de imagen no aparecen en GET /v1/models. Ese endpoint lista los modelos de lenguaje, embeddings y voz; el registro de imagen vive en GET /api/images/models. Un modelo de imagen desconocido vuelve como model_not_found desde el propio endpoint de imágenes.
El streaming se rechaza explícitamente, en vez de ignorarse: Streaming is not supported for image generation on this API.