Tutorial

Cómo cambiar el estilo de una imagen con IA: guía de transferencia de estilo imagen a imagen con la API de hiapi

Sep 4, 2026

Cambiar el estilo de una foto con IA —convertir una toma casual en un fotograma de anime, una foto de producto de estudio o una ilustración en acuarela— no es un endpoint especial de "transferencia de estilo". Es simplemente una llamada normal de imagen a imagen: envías una imagen de origen y una instrucción de texto que indica el estilo objetivo, y el modelo devuelve una nueva imagen. Lo que realmente determina si obtienes un cambio de estilo limpio o una regeneración a medias es cómo redactas esa instrucción, no algún parámetro ajustable. Esta guía describe el mecanismo de solicitud en la API unificada de tareas de hiapi, el patrón de prompt que evita que el cambio de estilo se desvíe hacia una imagen nueva, y cómo elegir entre dos modelos de imagen a imagen verificados según cuánta libertad creativa desees.

Qué necesitas preparar

Una clave de API de hiapi: obténla desde tu panel de control. Se coloca en el encabezado Authorization: Bearer sk-... de cada solicitud.
Una URL de imagen de origen accesible públicamente. Los servidores de hiapi descargan la imagen por sí mismos, por lo que las rutas localhost o los buckets privados sin URL firmada no funcionarán. Las URL prefirmadas de S3/R2/GCS sí sirven.

Cada id de modelo y campo a continuación se revalidó contra la API en línea antes de publicarse, incluida una prueba de error forzado para confirmar los valores de enumeración actuales.

Por qué el cambio de estilo necesita una "cláusula de conservación"

Ninguno de los dos modelos de esta guía ofrece un parámetro numérico de intensidad o fuerza: enviar uno (strength: 0.5) se rechaza directamente con el error additional properties 'strength' not allowed. La intensidad del estilo se controla completamente mediante la redacción del prompt, lo que significa que una instrucción como "make this a Studio Ghibli anime frame" solo le dice al modelo qué añadir, pero no qué mantener sin cambios: la identidad del sujeto, la pose y la composición pueden ser reinterpretadas libremente por el modelo.

La solución es escribir siempre dos cláusulas en el prompt:

Estilo objetivo, expresado con una referencia visual concreta (un medio, un género artístico, una apariencia específica: "anime cel-shading", "1970s film photography", "clean studio product shot on white"), en lugar de adjetivos vagos como "cooler".
Una cláusula de conservación explícita: nombra lo que no debe cambiar: "keep the same subject, pose, and composition", "keep the text and logo unchanged", "keep the camera angle".

Un prompt como "Restyle this photo as a woodblock print. Keep the subject's pose, framing, and the position of every object in the scene." le da al modelo un objetivo y una restricción en la misma instrucción, que es la mayor palanca para obtener un cambio de estilo en lugar de una regeneración.

Ejemplo mínimo funcional: curl

Este ejemplo usa seedream-5.0-pro/image-to-image, que funciona bien para cambiar el estilo y tiene un esquema estricto y completamente validado:

curl -s -X POST https://api.hiapi.ai/v1/tasks \\\n  -H "Authorization: Bearer sk-YOUR_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "model": "seedream-5.0-pro/image-to-image",\n    "input": {\n      "prompt": "Restyle this portrait as a watercolor painting with visible brush texture and soft bleeding edges. Keep the subject'\\''s pose, expression, and framing exactly as in the source.",\n      "image_urls": ["https://your-bucket.example.com/portrait.jpg"],\n      "aspect_ratio": "3:4",\n      "resolution": "2K"\n    }\n  }'\n

aspect_ratio es obligatorio y proviene de una enumeración fija: actualmente 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9. Este endpoint no tiene una opción de "coincidir con la imagen de origen", así que elige el valor más cercano a la proporción real de la imagen de origen (foto vertical → 3:4 o 9:16, no 16:9) para evitar que el modelo añada bordes o recorte la composición para adaptarla.

Tras crearse correctamente, devuelve el id de tarea en data.taskId:

{ "data": { "taskId": "<your-task-id>" } }\n

Consulta repetidamente hasta llegar al estado terminal:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \\\n  -H "Authorization: Bearer sk-YOUR_KEY"\n

data.status termina siendo success (la salida está en data.output[0].url) o fail (los detalles están en data.error).

Script completo de Python: crear, consultar, descargar

Usa solo la biblioteca estándar:

import json\nimport time\nimport urllib.request\n\nAPI = "https://api.hiapi.ai/v1/tasks"\nKEY = "sk-YOUR_KEY"\n\n\ndef call(url, payload=None):\n    req = urllib.request.Request(\n        url,\n        data=json.dumps(payload).encode() if payload is not None else None,\n        headers={\n            "Authorization": f"Bearer {KEY}",\n            "Content-Type": "application/json",\n        },\n        method="POST" if payload is not None else "GET",\n    )\n    with urllib.request.urlopen(req) as resp:\n        return json.load(resp)\n\n\n# 1. Create the restyle task\ncreate = call(API, {\n    "model": "seedream-5.0-pro/image-to-image",\n    "input": {\n        "prompt": (\n            "Restyle this street photo as a 1980s film-grain photograph with warm, "\n            "faded colors. Keep the same subject, pose, and every object in the "\n            "same position in the frame."\n        ),\n        "image_urls": ["https://your-bucket.example.com/street.jpg"],\n        "aspect_ratio": "16:9",\n        "resolution": "2K",\n    },\n})\ntask_id = create["data"]["taskId"]\nprint("task created:", task_id)\n\n# 2. Poll until terminal state\nwhile True:\n    task = call(f"{API}/{task_id}")["data"]\n    if task["status"] == "success":\n        break\n    if task["status"] == "fail":\n        err = task.get("error") or {}\n        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")\n    time.sleep(5)\n\n# 3. Download immediately -- output URLs expire\nimage_url = task["output"][0]["url"]\nurllib.request.urlretrieve(image_url, "restyled.png")\nprint("saved restyled.png")\n

Elige el modelo según la libertad creativa que desees

Ambos modelos se revalidaron en línea y ninguno acepta el parámetro strength, pero difieren en cuánto puedes controlar la influencia de la imagen de origen:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

	`seedream-5.0-pro/image-to-image`	`grok-imagine-quality/image-to-image`
Imágenes de referencia	1–10 URL públicas	1–3 URL públicas
`resolution`	`1K` / `2K` (mayúsculas)	`1k` / `2k` (minúsculas) — opcional
Control de composición	Enumeración fija de 8 valores de `aspect_ratio`, sin coincidencia automática	`aspect_ratio: "auto"` sigue el encuadre de entrada
Ideal para	Cambio de estilo preciso con una sola referencia, cuando ya conoces la proporción objetivo	Cambio de estilo rápido en el que deseas que la salida herede la composición exacta de la imagen de origen sin elegir la proporción manualmente

Si tu cláusula de conservación incluye "same framing" y no quieres calcular manualmente la relación de aspecto de la imagen de origen, usar grok-imagine-quality/image-to-image con aspect_ratio: "auto" es la ruta más directa: sustitúyelo en la solicitud anterior, con image_urls de hasta 3 elementos y resolution en minúsculas 2k.

Consideraciones para producción

En el servidor, prioriza las devoluciones de llamada sobre el sondeo. Añade un objeto callback al solicitar y hiapi hará un POST una vez al llegar al estado terminal, sin que tengas que sondear:

{\n  "model": "seedream-5.0-pro/image-to-image",\n  "input": { "...": "..." },\n  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }\n}\n

Trata la carga útil de la devolución de llamada como una señal y no como la fuente de la verdad: obtén de ella el id de tarea y vuelve a obtener GET /v1/tasks/<id> por tu cuenta antes de actuar. Para scripts y notebooks, sondear cada 5 segundos es suficiente.

Haz que los reintentos sean idempotentes. Al crear una tarea, almacena tu propio mapeo imagen de origen → taskId. Si tu proceso se cae a mitad del sondeo, al reiniciar debes reasociar el taskId almacenado en lugar de reenviar la solicitud, ya que reenviarla supone una segunda tarea facturada.

Errores que encontrarás en la práctica:

401 permission_denied: clave con formato incorrecto o ausente. El encabezado debe ser exactamente Authorization: Bearer sk-....
400 INVALID_REQUEST: infracción del esquema, por ejemplo aspect_ratio: value must be one of '1:1', '4:3', ... o additional properties 'strength' not allowed. Los esquemas de ambos modelos son estrictos: no apliques parámetros de una familia de modelos a otra.
image_urls must be an array: se pasó una cadena sin formato de lista en lugar de una lista, incluso con una sola imagen de referencia.

Lecturas relacionadas

Referencia completa campo por campo del modelo principal de esta guía: Cómo usar seedream-5.0-pro/image-to-image.
Prompts de cambio de estilo listos para copiar con salidas reales de antes y después: Recetas de prompts de imagen a imagen de Grok Imagine Quality.
Comparación de calidad de salida entre modelos con la misma edición: Las mejores API de imagen a imagen de 2026.
Precios actuales por imagen: página de precios.
Referencia completa de la API: documentación de hiapi.

Preguntas frecuentes

¿La transferencia de estilo tiene un control deslizante de intensidad o fuerza?\nNo. Ninguno de los dos modelos de esta guía acepta el campo strength: enviarlo se rechaza como propiedad no reconocida. La intensidad del estilo se controla completamente mediante la especificidad y la fuerza de la descripción del estilo en el prompt.

¿Cómo evito que el modelo cambie la pose o la identidad de mi sujeto?\nAñade al prompt una cláusula de conservación explícita que nombre lo que debe permanecer sin cambios: pose, expresión, composición, posición de los objetos. Cuando las restricciones se escriben explícitamente en lugar de sugerirse, el modelo es más conservador al cambiar el estilo.

¿Puedo conservar automáticamente la relación de aspecto exacta de la imagen de origen?\nEn grok-imagine-quality/image-to-image sí: establece aspect_ratio: "auto". En seedream-5.0-pro/image-to-image no hay opción automática; elige de su enumeración fija el valor más cercano a la proporción real de la imagen de origen.

¿Mi imagen de origen debe ser una URL pública?\nDebe poder ser descargada por los servidores de hiapi mediante HTTPS. Las URL prefirmadas de buckets privados sirven; las rutas localhost o no autenticadas e inaccesibles no.

¿Puedo generar varias variantes de estilo a partir de una foto en paralelo?\nSí: cada variante es una tarea independiente. Lanza varias llamadas POST /v1/tasks con los mismos image_urls y distintas instrucciones de estilo, y luego sondea o usa devoluciones de llamada para cada taskId por separado.

¿Cuál es la diferencia entre cambiar el estilo y el retoque o la eliminación de objetos?\nCambiar el estilo modifica cómo se renderiza toda la imagen mientras mantiene el contenido igual; el retoque o la eliminación de objetos modifica zonas específicas mientras mantiene el estilo de renderizado igual. Son patrones de prompt diferentes en el mismo tipo de endpoint de imagen a imagen. Si lo que realmente necesitas es retoque y eliminación de objetos, consulta la guía de retoque y eliminación de objetos.

Conclusiones clave

Redacta el prompt de cambio de estilo en dos partes: primero el estilo objetivo y luego una cláusula de conservación explícita que nombre lo que no debe cambiar (pose, composición, posición de los objetos).
Ninguno de los dos modelos verificados tiene parámetro de intensidad o fuerza: la intensidad del estilo proviene totalmente de la fuerza de la descripción del estilo en el prompt.
En seedream-5.0-pro/image-to-image, aspect_ratio es una enumeración fija de 8 valores sin opción de coincidencia automática; elige tú mismo la proporción más cercana a la imagen de origen.
grok-imagine-quality/image-to-image admite aspect_ratio: "auto", que sigue la composición propia de la imagen de entrada; es útil cuando no quieres calcular la proporción manualmente.
Para servidores, usa callback.url con when:"final" en lugar del sondeo, y almacena tu propio mapeo imagen de origen → taskId para reasociar en caso de caída y reintento en lugar de reenviar.