API gratis de Qwen-Image-2.1: cómo usarla con ModelScope

Puedes llamar a Qwen-Image-2.1 desde tu programa con la API gratuita de ModelScope. La página del modelo publica un ejemplo para el identificador exacto Qwen/Qwen-Image-2.1: envías una solicitud, recibes un identificador de tarea y consultas su estado hasta poder descargar la imagen. Para utilizarla necesitas una cuenta de ModelScope vinculada a una cuenta de Alibaba Cloud con la identidad verificada, un token de acceso y saldo disponible.

La gratuidad funciona mediante créditos de cómputo llamados 魔粒, que aquí denominaremos «créditos de ModelScope». No equivale a una cantidad fija de imágenes al día ni a un servicio ilimitado. Las condiciones que siguen corresponden a la documentación consultada el 23 de septiembre de 2026. El código es un ejemplo basado en esa documentación; no hemos realizado una generación real con una cuenta.

Prepara la cuenta y consigue el token

El primer paso es comprobar que puedes completar los requisitos de acceso. Según la introducción oficial de API-Inference, registrarte en ModelScope y obtener un token no basta: también debes vincular una cuenta de Alibaba Cloud que haya completado la verificación de identidad.

1. Regístrate o inicia sesión en ModelScope y completa los datos del perfil, incluido un correo electrónico verificado.
2. Vincula tu cuenta de Alibaba Cloud y completa su verificación de identidad.
3. Abre la sección de tokens de acceso de ModelScope. La guía de tokens explica este mecanismo de autenticación.
4. Entra en Qwen/Qwen-Image-2.1 y localiza API-Inference. Para seguir esta guía, el proveedor debe ser la comunidad ModelScope, identificada como 魔搭社区.
5. Revisa el saldo y el consumo previsto que muestra ese panel antes de enviar la primera solicitud.

La documentación consultada no incluye una tabla que garantice el acceso desde todos los países. Si usas el servicio desde España u otro país, comprueba que tu cuenta admite el proceso de vinculación y verificación. Tener la interfaz disponible en el navegador no demuestra que ya puedas usar la API.

Conserva el token en el servidor o en una variable de entorno de tu equipo. No lo incluyas en JavaScript que se descargue en el navegador ni lo subas al repositorio. Es un token de ModelScope, no una clave de DashScope.

Cuántas imágenes puedes generar gratis

No hay una cifra de imágenes de Qwen-Image-2.1 que podamos garantizar con la información pública consultada. El límite actual depende del saldo de créditos de ModelScope y del consumo específico del modelo, que debe aparecer en su panel. No pudimos confirmar ese consumo exacto en la vista sin iniciar sesión.

La documentación de créditos describe estas reglas:

La documentación indica que las recompensas se conceden al realizar las acciones correspondientes. No hemos comprobado el abono en una cuenta. Además, la tabla de recompensas habla de validez durante el día y el texto general especifica 24 horas: usa el registro de tu cuenta para comprobar la caducidad concreta. Se consumen primero los créditos que caducan antes.

Los límites de API-Inference distinguen categorías con consumos de 0,5, 1 o 2 créditos por llamada. Eso no permite asignar automáticamente Qwen-Image-2.1 a una categoría. Por tanto, sumar 200 y 50 y convertir el resultado en «250 imágenes gratis» sería incorrecto.

También hay límites de concurrencia que cambian según la carga de la plataforma. ModelScope describe este servicio como una experiencia gratuita, no comercial y sin ánimo de lucro; no está destinado a trabajos en línea que necesiten mucha concurrencia o un acuerdo de nivel de servicio. Para empezar, envía una tarea cada vez y espera a conocer su resultado.

Genera una imagen con Python: envío, estado y descarga

La API es asíncrona. El POST inicial crea una tarea; no devuelve necesariamente la imagen lista. Estos son los datos que debes mantener al adaptar el ejemplo de la página del modelo:

Instala las dependencias en un entorno de Python y configura la variable en la misma terminal desde la que ejecutarás el programa:

bash
python -m pip install requests Pillow
export MODELSCOPE_TOKEN="tu_token_de_modelscope"

En PowerShell, la asignación equivalente es $env:MODELSCOPE_TOKEN="tu_token_de_modelscope". Sustituye el marcador únicamente en tu equipo.

Guarda lo siguiente como qwen_image.py. El ejemplo conserva las rutas, cabeceras y campos documentados. Añadimos límites de tiempo, un plazo máximo de consulta y guardado en PNG como decisiones de implementación; no son resultados de una prueba real del servicio.

python
import os
import time
from io import BytesIO
from pathlib import Path

import requests
from PIL import Image

BASE_URL = "https://api-inference.modelscope.cn"
TOKEN = os.environ.get("MODELSCOPE_TOKEN")
if not TOKEN:
    raise SystemExit("Define MODELSCOPE_TOKEN antes de ejecutar el programa.")

HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

# Una sola solicitud de creación; no repetimos automáticamente el POST.
response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={**HEADERS, "X-ModelScope-Async-Mode": "true"},
    json={
        "model": "Qwen/Qwen-Image-2.1",
        "prompt": "Un gato dorado sobre una mesa de madera, luz suave de ventana",
    },
    timeout=(10, 60),
)
response.raise_for_status()
task_id = response.json()["task_id"]
print(f"Tarea creada: {task_id}")

# Diez minutos de espera local, sin presuponer la duración del servicio.
deadline = time.monotonic() + 600
while True:
    remaining = deadline - time.monotonic()
    if remaining <= 0:
        raise TimeoutError(f"Plazo agotado. Conserva el task_id: {task_id}")

    result = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers={**HEADERS, "X-ModelScope-Task-Type": "image_generation"},
        timeout=(min(10, remaining / 2), min(30, remaining / 2)),
    )
    result.raise_for_status()
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Plazo agotado. Conserva el task_id: {task_id}")

    task = result.json()
    status = task.get("task_status")
    if status == "FAILED":
        raise RuntimeError(f"La generación ha fallado. Tarea: {task_id}")
    if status == "SUCCEED":
        images = task.get("output_images") or []
        if not images:
            raise RuntimeError("La tarea terminó sin una URL de imagen.")

        # La descarga no lleva el token de ModelScope.
        download = requests.get(images[0], timeout=(10, 60))
        download.raise_for_status()
        output = Path("qwen-image-2-1.png")
        with Image.open(BytesIO(download.content)) as image:
            image.save(output, format="PNG")
        print(f"Imagen guardada en: {output.resolve()}")
        break

    time.sleep(max(0, min(5, deadline - time.monotonic())))

Ejecútalo con python qwen_image.py. Primero debería imprimir el identificador de tarea. El flujo solo se considera completado cuando el estado es SUCCEED, se obtiene una URL de resultado y la descarga se guarda correctamente como qwen-image-2-1.png.

El formato PNG conserva el canal de transparencia si el resultado lo contiene; no convierte por sí mismo una imagen opaca en una imagen transparente. La solicitud de descarga tampoco utiliza la cabecera Authorization: el token sirve para hablar con la API de ModelScope y no debe reenviarse al servidor que aloje la imagen.

Los diez minutos son el plazo elegido para este programa, no una promesa sobre la velocidad del modelo. Si se agota, la tarea remota podría seguir activa: conserva su task_id y consulta su estado antes de volver a crear otra.

Si la solicitud no termina, identifica dónde se ha detenido

El punto de fallo determina el siguiente paso. No vuelvas a ejecutar el programa entero sin mirar primero si ya se creó una tarea.

Las restricciones de saldo y concurrencia proceden de las condiciones de ModelScope. La tabla es una guía para localizar el problema, no una relación de errores reproducidos en una prueba.

Otra opción para experimentar: el Space oficial de Qwen

El Space de Qwen-Image-2.1 en Hugging Face ofrece una demostración con acceso mediante el cliente de Gradio. Su apartado Use via API publica el método /generate_with_enhance. Puede servir para explorar la demostración desde Python sin administrar una GPU propia:

bash
python -m pip install gradio_client

python
from gradio_client import Client

client = Client("Qwen/Qwen-Image-2.1")
result = client.predict(
    input_images=[],
    original_prompt="Un gato dorado sobre una mesa de madera",
    api_name="/generate_with_enhance",
)
print(result)

Este fragmento sigue el esquema público del Space, en el que los demás parámetros tienen valores predeterminados. La respuesta documentada incluye la imagen, la semilla y el texto reformulado de la petición. Tampoco hemos ejecutado esta generación. Si cambia la interfaz, copia el ejemplo actualizado de Use via API; la disponibilidad y la cola de la demostración no constituyen una cuota garantizada para tu aplicación.

No confundas este cliente con una API comercial de DashScope. Tampoco hay contradicción entre un Space accesible mediante Gradio y que la ficha del modelo en Hugging Face indique que no está desplegado por ningún Inference Provider: son servicios distintos.

Antes de llevarlo a una aplicación comercial

Poder probar el modelo sin pagar no resuelve por sí solo el permiso para explotarlo comercialmente. La Qwen Research License de Qwen-Image-2.1 limita el uso de los materiales del modelo a investigación y evaluación, y exige una autorización separada para su uso comercial. Esto no permite concluir, sin analizar otros términos, que cualquier imagen generada tenga exactamente las mismas restricciones. Comprueba la licencia aplicable al uso que harás del modelo y las condiciones del proveedor que lo aloja.

Además, la API gratuita de la comunidad ModelScope tiene sus propias condiciones de experiencia no comercial. Si necesitas atender a clientes, asumir picos de solicitudes o pactar disponibilidad, ese cambio de uso requiere revisar tanto el servicio como los permisos.

La tabla oficial de la API de imágenes de Alibaba Model Studio, actualizada el 22 de septiembre de 2026, no incluía Qwen-Image-2.1 cuando se consultó para esta guía. No sustituyas el identificador por uno de Qwen-Image-2.0 o 3.0 esperando utilizar el mismo modelo, ni traslades sus precios o promociones a 2.1.

Si tu objetivo es ejecutar los pesos en tu propia máquina, consulta la guía para instalar Qwen-Image-2.1 en local. Esa vía cambia los requisitos de hardware y el coste de cómputo; descargar los pesos no proporciona una API alojada gratuita.