Generación de imágenes
Conecta GPT Image, Seedream y modelos de imagen configurados.
/v1/images/generationshttps://api.hanrouter.ai/v1Gestionar claves APIURL 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.
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.
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.
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.
{
"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.
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 -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
{
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}