Generación de imágenes

Conecta GPT Image, Seedream y modelos de imagen configurados.

POST/v1/images/generations
https://api.hanrouter.ai/v1Gestionar claves API

URL y autenticación

Usa https://api.hanrouter.ai/v1 como URL base compatible con OpenAI y Authorization: Bearer $HANROUTER_API_KEY. No dupliques /v1. Todos los fabricantes usan tu clave HanRouter, no una clave del proveedor.

Para Anthropic SDK y Claude Code usa https://api.hanrouter.ai sin /v1; el cliente añade /v1/messages. Usa la interfaz compatible con OpenAI para Google.

Antes de llamar: modelos y permisos

Consulta GET /v1/models y usa un ID de imagen exacto de tu clave. La plaza muestra tipos de salida y precios; aparecer en la lista no garantiza todos los endpoints o parámetros. El grupo también debe permitir generar imágenes.

Texto a imagen: solicitud mínima

Configura HANROUTER_API_KEY y sustituye YOUR_IMAGE_MODEL_ID por un ID disponible. Empieza con model, prompt y n; añade size, quality o response_format solo si se admiten. El comando crea una generación real y puede generar cargos.

Ejemplo de solicitud
curl --max-time 300 "https://api.hanrouter.ai/v1/images/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "A golden bull in front of a modern city skyline, cinematic lighting",
  "n": 1
}'

Parámetros y diferencias entre modelos

model y prompt son strings obligatorios. n es la cantidad; empieza con 1 y respeta los límites. size suele usar ANCHOxALTO, como 1024x1024, pero los tamaños varían. quality y response_format dependen del modelo; no reutilices parámetros de otro proveedor sin comprobarlos.

Algunos modelos Gemini o canales usan Chat Completions multimodal o un protocolo nativo en lugar de Images. Estos ejemplos requieren un canal compatible. Ante errores de response_modalities o de protocolo, conserva el ID y contacta con soporte en vez de repetir solicitudes con otros nombres.

Imagen a imagen y edición

Los protocolos varían. Un canal Grok Imagine compatible puede aceptar image: {"url":"https://..."} en POST /v1/images/generations. Es un objeto, no un string URL. El proveedor debe acceder a la referencia. El campo no es universal; confirma el soporte del canal.

Ejemplo de solicitud
curl --max-time 300 "https://api.hanrouter.ai/v1/images/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_GROK_IMAGE_MODEL_ID",
  "prompt": "Turn this reference into a watercolor illustration",
  "image": {
    "url": "https://example.com/reference.png"
  }
}'

Subir imagen local: edición multipart

El estudio sube archivos a POST /v1/images/edits para modelos con edición. Usa -F para multipart/form-data y deja que cURL establezca Content-Type y boundary; no uses application/json. Sustituye reference.png por tu PNG/JPEG/WebP. Límites, máscaras y múltiples imágenes dependen del modelo.

Ejemplo de solicitud
curl --max-time 300 "https://api.hanrouter.ai/v1/images/edits" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -F "model=$HANROUTER_IMAGE_MODEL" \
  -F 'prompt=Keep the subject and change the background to a city at sunset' \
  -F 'n=1' \
  -F 'image=@reference.png'

Respuesta: URL y Base64

Los resultados síncronos suelen usar data[].url o data[].b64_json; no se garantizan ambos. Decodifica b64_json antes de guardar. Las URL pueden caducar. Son estructuras ilustrativas, no resultados reales. Procesa campos opcionales como usage o revised_prompt según la respuesta.

Ejemplo de solicitud
{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

{
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_BYTES>"
    }
  ]
}

Python: generar y guardar una imagen

Usa la biblioteca estándar de Python. Configura HANROUTER_API_KEY y HANROUTER_IMAGE_MODEL; procesa URL o Base64 y guarda PNG, JPEG o WebP según la firma. No incluyas credenciales en el código.

Ejemplo de solicitud
import base64, json, os, pathlib, urllib.request

payload = {"model": os.environ["HANROUTER_IMAGE_MODEL"],
           "prompt": "A golden bull in a modern city, cinematic lighting", "n": 1}
request = urllib.request.Request(
    "https://api.hanrouter.ai/v1/images/generations",
    data=json.dumps(payload).encode(),
    headers={"Authorization": "Bearer " + os.environ["HANROUTER_API_KEY"],
             "Content-Type": "application/json"})
with urllib.request.urlopen(request, timeout=300) as response:
    result = json.load(response)
for index, item in enumerate(result["data"], 1):
    if item.get("b64_json"):
        image = base64.b64decode(item["b64_json"])
    else:
        with urllib.request.urlopen(item["url"], timeout=60) as response:
            image = response.read()
    extension = ".png" if image.startswith(b"\x89PNG") else ".jpg" if image.startswith(b"\xff\xd8") else ".webp"
    pathlib.Path(f"image-{index}{extension}").write_bytes(image)

Imágenes asíncronas y diagnóstico

Si está habilitado, envía a POST /v1/images/generations/async o /v1/images/edits/async, guarda request_id / task_id / id y consulta GET /v1/images/tasks/{id} con la misma clave. Sigue status, result y data reales. Cambia al endpoint síncrono solo tras confirmar que el 404 significa endpoint deshabilitado, no modelo inexistente.

403 permission_error / Image generation is not enabled for this group: solicita habilitar el permiso del grupo. Para 400 revisa modelo, tamaño, imagen y protocolo; 401 la clave; 402/403 saldo, cuota y permisos; 429 Retry-After. En 5xx o timeout conserva X-Request-Id, hora y respuesta censurada, y revisa tareas/uso antes de reenviar. Consulta /docs/generate-video para envío, consulta y primer fotograma.

Parámetros

model
String obligatorio: ID exacto disponible para tu clave.
prompt
String: descripción para imágenes o adaptador de vídeo prompt; content nativo depende del canal.
size
String opcional: tamaño admitido por el modelo.
n
Entero opcional: cantidad dentro de los límites.
quality
String opcional: nivel de calidad específico del modelo.
image
Object opcional: {url: "https://..."} en canales compatibles; edición local usa multipart /images/edits.

Ejemplo de solicitud

Los ejemplos usan IDs configurados. Los permisos del grupo de la clave determinan el acceso; consulta GET /v1/models.

cURL
curl -X POST "https://api.hanrouter.ai/v1/images/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "your-model-id",
  "prompt": "A red bicycle beside a tree"
}'

Ejemplo de respuesta

JSON · estructura de ejemplo
{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}