Cómo usar la API wan2.7-image-standard en hiapi: generación de imágenes a partir de texto y edición con imágenes de referencia

wan2.7-image-standard es el nivel estándar del modelo Tongyi Wanx Wan 2.7 Image. La razón por la que merece su propia página es esta: un mismo ID de modelo admite tanto la generación de imágenes a partir de texto como la edición de imágenes basada en referencias, con soporte de hasta 2K, y se factura a un precio fijo de $0.0345 por imagen, más económico que el nivel Pro con soporte 4K. Esta guía ofrece una solicitud lista para ejecutar, el esquema de entrada exacto (verificado contra la API en línea), la ruta de edición con imágenes de referencia y los comportamientos límite que debes gestionar en producción.

Todo el contenido de las secciones de esquema y errores a continuación se confirmó sondeando el endpoint /v1/tasks en línea durante la redacción: las listas de enumeraciones, los conjuntos de campos aceptados y las formas de respuesta de fallo se citan de respuestas reales de la API, no de memoria.

Qué vas a construir y qué necesitas preparar

Vas a enviar un prompt (opcionalmente con imágenes de referencia), consultar hasta que la tarea se complete y luego descargar la imagen. Primero necesitas una cosa: obtener una clave de API desde la guía de inicio rápido de hiapi y exportarla como HIAPI_API_KEY. No existe una ruta sin clave: cada solicitud se autentica mediante Authorization: Bearer sk-<your-key>.

wan2.7-image-standard se ejecuta sobre la API de tareas asíncronas de hiapi: primero haces POST /v1/tasks para crear la tarea y luego consultas el endpoint de detalles hasta que informe un estado terminal.

Generación a partir de texto: solicitud mínima

Crear la tarea:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Hora azul tras la lluvia, un pequeño estudio de cerámica en un callejón tranquilo y vacío, con farolillos de papel cálidos colgando, teteras esmaltadas en el escaparate, luces reflejadas en el suelo de piedra mojado, una bicicleta apoyada contra la pared, fotografía cinematográfica de 35 mm, alto nivel de detalle",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

El id de la tarea en la respuesta se encuentra en data.taskId:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D5..." }, "message": "success" }

Luego consulta GET /v1/tasks/<taskId> hasta que data.status sea success y lee la URL de la imagen desde data.output[0].url:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # edición con imágenes de referencia (ver la siguiente sección)
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # error de validación síncrona (p. ej., valor de enumeración inválido)
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # fallo en estado terminal: no sigas consultando
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # guarda los bytes de inmediato: consulta la nota sobre expiración más abajo

aspect_ratio y resolution son opcionales (el modelo tiene valores predeterminados), pero configúralos explícitamente: resolution solo acepta 1K o 2K, y ambos se facturan igual, así que no hay motivo de coste para dejarlo en el valor predeterminado.

Edición basada en imágenes de referencia: el mismo ID de modelo, más image_urls

Aquí es donde el nivel estándar se diferencia del nivel Pro. Pasa imágenes de referencia en image_urls (un array, hasta 9 imágenes de referencia según las especificaciones del modelo) y el modelo las editará o recompondrá basándose en ellas, siguiendo a la vez tu prompt de texto:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Coloca este producto sobre una encimera de cocina de mármol bañada por el sol, con hierbas frescas al lado, luz suave de la mañana, fotografía de producto de estilo de vida",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

En Python, es el parámetro image_urls=[...] que se pasa a la función auxiliar anterior; nada más cambia. Incluso con imágenes de referencia, prompt sigue siendo obligatorio (la API rechaza solicitudes sin prompt: missing required field "prompt").

El nombre del campo importa: es image_urls. Los nombres alternativos que parecen razonables —reference_image_urls, image_input, input_urls— son rechazados por el esquema con additional properties '<name>' not allowed. Si estás portando código desde el endpoint de edición de otro modelo, esto es lo primero que debes corregir.

El esquema de entrada exacto

El esquema es estricto: cualquier campo que no esté en la siguiente lista devuelve 400 INVALID_REQUEST con additional properties '<name>' not allowed. Estos son todos los campos que acepta:

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	Obligatorio tanto para la generación a partir de texto como para la edición. Puede usarse en inglés o chino.
aspect_ratio	string enum	No	Uno de: 1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8. Cualquier otro valor (p. ej., 3:2) → 400.
resolution	string enum	No	Solo 1K o 2K. Este nivel no admite 4K.
image_urls	string[]	No	Imágenes de referencia para la edición (máximo 9). Al pasarlas se cambia al modo de referencia.
seed	integer	No	Para obtener resultados reproducibles.

Campos que podrías imaginar pero que este modelo no acepta: negative_prompt, n, size y prompt_optimizer son rechazados como propiedades desconocidas. No hay parámetro de lote (n): envía una tarea por imagen.

Consideraciones de producción y comportamiento medido

Recibir 200 al enviar no significa que la imagen se vaya a generar. wan2.7-image-standard valida los valores de enumeración de forma síncrona (un resolution o aspect_ratio incorrecto hace que el POST falle de inmediato con 400 INVALID_REQUEST), pero no valida las URL de referencia al enviar. Las entradas de image_urls mal formadas o inaccesibles se aceptan, devuelven 200 y un taskId, y luego la tarea falla aproximadamente un segundo después. Verifiqué esto directamente: una tarea creada con una URL de referencia no válida devolvió el siguiente estado terminal

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

La consecuencia práctica es: consulta siempre hasta el estado terminal y gestiona según la rama data.status == "fail" (leyendo data.error). Las tareas fallidas se informan como HTTP 200 con data.status: "fail": la información de fallo está en data.error, no en un error HTTP de nivel superior. Asegúrate de que tus URL de referencia sean accesibles públicamente antes de enviar.

Descarga la salida de inmediato. data.output[0].url es un enlace temporal con una marca de tiempo expireAt, no un recurso CDN permanente. Obtén los bytes en el momento en que la tarea tenga éxito y transfiérelos a tu propio almacenamiento; una URL expirada dará 404. Si ya te has encontrado con este problema, consulta por qué tu URL de salida de hiapi da 404 y cómo solucionarlo.

Sondeo vs. callback. El ejemplo anterior consulta cada cinco segundos, lo cual está bien para scripts y lotes pequeños. Para el rendimiento en producción, adjunta callback en la solicitud de creación para que hiapi te notifique en el evento de estado terminal en lugar de mantener tú la conexión; consulta los detalles del mecanismo en la documentación de creación de tareas.

Estándar vs. Pro: qué nivel usar

hiapi aloja dos niveles de Wan 2.7 Image, que son ID de modelo distintos, no parámetros:

• wan2.7-image-standard (esta guía): generación a partir de texto y edición con imágenes de referencia, 1K/2K, facturado a un precio fijo de $0.0345 por imagen independientemente de la resolución.
• wan2.7-image/text-to-image: nivel Pro, solo generación a partir de texto, hasta 4K, precio fijo de $0.08 por imagen. Consulta la página de Wan 2.7 Image Pro y la guía detallada sobre cómo usarlo para generar imágenes de producto de ecommerce en 4K.

Elige el nivel estándar cuando necesites edición basada en imágenes de referencia, o cuando 2K sea suficiente y quieras pagar menos de la mitad del precio por imagen de Pro. Usa Pro solo cuando necesites específicamente salida nativa en 4K: es lo único que el nivel estándar no puede hacer. Consulta los precios actuales de ambos en la página de precios.

Preguntas frecuentes

¿wan2.7-image-standard admite edición de imágenes o solo generación a partir de texto? Admite ambas, desde el mismo ID de modelo. Añade el array image_urls para cambiar a la edición basada en imágenes de referencia; omítelo para la generación pura a partir de texto.

¿Cuál es la resolución máxima? 2K. El campo resolution solo acepta 1K y 2K; la API en línea rechaza cualquier otro valor. Si necesitas 4K, usa el nivel Pro (wan2.7-image/text-to-image).

¿Por qué mi tarea devolvió 200 y luego falló? Las URL de referencia no se comprueban al enviar, solo durante la ejecución. Las entradas de image_urls inaccesibles o mal formadas crean la tarea (HTTP 200) y luego fallan con estado terminal INVALID_REQUEST. Consulta data.status y verifica que tus URL sean públicas.

¿Puedo establecer un prompt negativo? No. negative_prompt no es un campo aceptado por este modelo (tampoco n, size ni prompt_optimizer). Guía el resultado mediante el prompt positivo y seed.