- Cuándo usar este inicio rápido
- Paso 1: Obtén tu clave API de Novita
- Paso 2: Confirma el endpoint y el modelo
- Paso 3: Envía tu primera solicitud
- Paso 4: Sondear para obtener tu resultado
- Ejemplo en Python: extremo a extremo
- Ejemplo con cURL
- Parámetros clave
- Lo que Qwen Image genera bien
- Errores comunes y soluciones
- FAQ
- Artículos recomendados
La API de texto a imagen de Qwen Image en Novita AI genera imágenes a partir de instrucciones textuales usando el modelo Qwen Image de 20B, la misma base que impulsa la API de edición de imágenes Qwen Image para tareas de edición precisas. Este inicio rápido cubre el flujo de trabajo asíncrono completo: enviar una solicitud de generación, obtener un ID de tarea, sondear hasta que finalice y recuperar la URL de tu imagen. El endpoint es POST https://api.novita.ai/v3/async/qwen-image-txt2img.
Cuándo usar este inicio rápido
Utiliza esta guía cuando necesites:
- Generar imágenes a partir de instrucciones textuales con renderizado de texto de alta calidad en inglés o chino mediante
POST /v3/async/qwen-image-txt2img. - Construir pipelines que creen pósters, activos gráficos o contenido ilustrado donde la legibilidad del texto dentro de la imagen sea importante.
- Prototipar rápidamente contra una API alojada en lugar de ejecutar el modelo de 20B en infraestructura GPU local.
El modelo Qwen Image es especialmente bueno generando imágenes con texto legible y con estilo incrustado en la salida: piensa en pósters, letreros, maquetas de productos y gráficos de portada. Si tu caso de uso implica editar una imagen existente en lugar de generar desde cero, consulta la API de edición de imágenes Qwen Image. Si deseas una visión general completa de las capacidades y benchmarks del modelo Qwen Image, el artículo de lanzamiento de Novita AI sobre Qwen Image cubre la arquitectura y los resultados de los benchmarks en detalle.
Paso 1: Obtén tu clave API de Novita
Crea una cuenta en Novita AI y navega a gestión de claves API. Genera una clave y guárdala como variable de entorno:
export NOVITA_API_KEY="tu_clave_api_aqui"
Mantén la clave fuera del código del lado del cliente, los bundles del frontend y el control de versiones.
Paso 2: Confirma el endpoint y el modelo
| Elemento | Valor |
|---|---|
| Endpunt de generación | POST https://api.novita.ai/v3/async/qwen-image-txt2img |
| Endpunt de sondeo de resultados | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| Modelo | Qwen Image (20B MMDiT) |
| Docs de la API | Referencia de Novita AI Qwen Image txt2img |
La API sigue un patrón asíncrono de dos pasos común a todos los endpoints de generación de imágenes de Novita AI. La llamada de generación devuelve solo un task_id; debes sondear el endpoint de resultados por separado hasta que la tarea se complete.
El precio es de $0.02 por imagen, consistente con el endpoint de edición de Qwen Image. Verifica la tarifa actual en la página de precios de Novita AI antes de construir una estimación de costos.
Paso 3: Envía tu primera solicitud
Haz POST al endpoint de generación con un prompt y un size opcional:
curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cinematic mountain landscape at sunrise, warm golden light, ultra-detailed, 8K",
"size": "1024*1024"
}'
Una respuesta 200 exitosa devuelve:
{
"task_id": "abc123..."
}
Guarda el task_id. Lo usarás en el siguiente paso.
Paso 4: Sondear para obtener tu resultado
Haz GET al endpoint de resultado de la tarea con el task_id como parámetro de consulta:
curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
-H "Authorization: Bearer $NOVITA_API_KEY"
La respuesta incluye un campo status. Sigue sondeando hasta que el estado sea TASK_STATUS_SUCCEED:
{
"task": {
"task_id": "abc123...",
"status": "TASK_STATUS_SUCCEED"
},
"images": [
{
"image_url": "https://...",
"image_url_ttl": "3600",
"image_type": "png"
}
]
}
La image_url es una URL con tiempo limitado: el valor image_url_ttl (en segundos) te indica cuánto tiempo sigue siendo válida. Descarga la imagen de inmediato o pásala por tu propio almacenamiento si necesitas acceso a largo plazo.
Valores de estado a manejar:
| Estado | Significado |
|---|---|
TASK_STATUS_QUEUED |
La solicitud está en cola, aún no ha comenzado |
TASK_STATUS_PROCESSING |
Generación en progreso |
TASK_STATUS_SUCCEED |
La imagen está lista; lee images[0].image_url |
TASK_STATUS_FAILED |
La generación falló; verifica task.reason |
Ejemplo en Python: extremo a extremo
Este script envía una solicitud de generación, sondea hasta que se completa e imprime la URL de la imagen.
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
def generate_image(prompt: str, size: str = "1024*1024") -> str:
response = requests.post(
f"{BASE_URL}/v3/async/qwen-image-txt2img",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"prompt": prompt, "size": size},
)
response.raise_for_status()
return response.json()["task_id"]
def poll_result(task_id: str, interval: float = 2.0, max_attempts: int = 60) -> str:
for _ in range(max_attempts):
response = requests.get(
f"{BASE_URL}/v3/async/task-result",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"task_id": task_id},
)
response.raise_for_status()
data = response.json()
status = data["task"]["status"]
if status == "TASK_STATUS_SUCCEED":
return data["images"][0]["image_url"]
elif status == "TASK_STATUS_FAILED":
reason = data["task"].get("reason", "unknown")
raise RuntimeError(f"Generation failed: {reason}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete after {max_attempts} polls")
if __name__ == "__main__":
prompt = (
"A poster reading 'Welcome to Novita AI' in bold neon letters "
"against a dark city skyline at night, cinematic lighting"
)
task_id = generate_image(prompt, size="1024*1024")
print(f"Task ID: {task_id}")
image_url = poll_result(task_id)
print(f"Image URL: {image_url}")
Ejemplo con cURL
Patrón de dos comandos para el flujo de trabajo completo:
# Paso 1: Enviar solicitud de generación
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-txt2img \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A serene Japanese garden with cherry blossoms, koi pond, morning mist, watercolor style",
"size": "1024*1536"
}' | python3 -c "import sys,json; print(json.load(sys.stdin)['task_id'])")
echo "Task ID: $TASK_ID"
# Paso 2: Sondear hasta completar
while true; do
STATUS=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY")
STATE=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['task']['status'])")
echo "Status: $STATE"
if [ "$STATE" = "TASK_STATUS_SUCCEED" ]; then
echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['images'][0]['image_url'])"
break
elif [ "$STATE" = "TASK_STATUS_FAILED" ]; then
echo "Generation failed"
break
fi
sleep 2
done
Parámetros clave
| Parámetro | Tipo | Obligatorio | Por defecto | Notas |
|---|---|---|---|---|
prompt |
string | Sí | — | Descripción textual de la imagen a generar. Soporta inglés y chino. |
size |
string | No | 1024*1024 |
Ancho × alto en píxeles, formateado como W*H. Cada dimensión: 256–1536. |
Opciones de tamaño a considerar:
| Caso de uso | Tamaño recomendado |
|---|---|
| Cuadrado (redes sociales, perfil) | 1024*1024 |
| Retrato (móvil, póster) | 1024*1536 |
| Paisaje (banner, miniatura) | 1536*1024 |
No hay parámetros separados de negative_prompt, steps o cfg_scale en este endpoint: el modelo maneja esas decisiones internamente. Enfoca tu prompt en lo que la imagen debe contener y su estilo visual.
Lo que Qwen Image genera bien
La arquitectura MMDiT de 20B le da a Qwen Image una ventaja genuina en algunas áreas específicas:
Texto en imágenes. La mayoría de los modelos de generación de imágenes tienen dificultades con el texto legible: las palabras se difuminan, las letras se intercambian y los diseños multilínea colapsan. Qwen Image maneja texto en inglés y chino con una precisión notablemente mejor. Pósters, letreros, etiquetas y gráficos con subtítulos son casos de uso viables, no un volado de moneda.
Consistencia semántica. Cuando un prompt describe una escena con múltiples elementos y relaciones espaciales específicas, Qwen Image tiende a respetar la intención del diseño de manera más confiable que arquitecturas más pequeñas o más antiguas.
Seguimiento de instrucciones a escala. Prompts largos y detallados que describen múltiples atributos (escena, iluminación, estilo, paleta de colores, objetos específicos) producen resultados que reflejan el prompt completo en lugar de aferrarse a una sola palabra clave.
Donde es menos adecuado: flujos de trabajo de generación en tiempo real o interactivos. El patrón asíncrono implica una latencia inherente entre la solicitud y el resultado. Si tu caso de uso requiere retroalimentación en subsegundos, este endpoint no es la opción adecuada.
Errores comunes y soluciones
401 No autorizado: Verifica que el encabezado Authorization esté formateado como Bearer <key> con un espacio después de Bearer. Confirma que la clave esté activa en la consola de Novita AI.
400 Solicitud incorrecta en size: El parámetro size debe usar * como separador (por ejemplo, 1024*1024), no x, × o un array JSON. Cada dimensión debe estar entre 256 y 1536.
TASK_STATUS_FAILED sin motivo: Generalmente causado por un prompt que activa el filtrado de contenido. Simplifica el prompt y vuelve a intentarlo. Evita prompts con violencia explícita, contenido sexual o contenido que pueda coincidir con los filtros de seguridad.
URL de imagen expirada (403 o 404 en la URL): El campo image_url_ttl te indica cuánto tiempo es válida la URL. Descarga la imagen inmediatamente después de que el sondeo tenga éxito, o guárdala en tu propio almacenamiento de objetos.
Sondeo lento: El tiempo de generación varía con la carga del servidor. Comenzar el sondeo en intervalos de 2 segundos es razonable. Si la tarea aún está TASK_STATUS_QUEUED después de 10 segundos, continúa sondeando; la profundidad de la cola puede aumentar durante las horas pico.
FAQ
¿Existe un endpoint compatible con OpenAI para Qwen Image txt2img?
No. El endpoint /v3/async/qwen-image-txt2img utiliza la API de imagen asíncrona nativa de Novita AI, no el formato de generación de imágenes de OpenAI. Si necesitas generación de imágenes compatible con OpenAI, Novita AI ofrece modelos FLUX y SDXL a través de endpoints compatibles; consulta la documentación de Novita AI.
¿Cuál es la diferencia entre este endpoint y el endpoint de edición de imágenes Qwen Image?
Este endpoint genera imágenes únicamente a partir de un prompt textual: no se necesita una imagen de entrada. El endpoint de edición de imágenes Qwen Image toma una imagen existente más una instrucción de texto y modifica la imagen en consecuencia. Usa txt2img cuando estés creando desde cero; usa edit cuando necesites cambiar algo en una imagen existente.
¿El modelo soporta relaciones de aspecto distintas del cuadrado?
Sí. Usa el parámetro size para establecer el ancho y la altura de forma independiente, en cualquier lugar de 256 a 1536 píxeles por dimensión. Las proporciones altas (por ejemplo, 1024*1536) funcionan bien para contenido vertical; las proporciones anchas (por ejemplo, 1536*1024) son adecuadas para banners y miniaturas.
¿Cómo obtengo resultados consistentes en múltiples generaciones?
No hay un parámetro seed en el endpoint txt2img. Cada solicitud produce un resultado diferente. Si necesitas una salida reproducible, guarda la URL de la imagen inmediatamente y almacena la imagen en tu propio almacenamiento en lugar de volver a generarla.
¿Puedo usar esta API en un trabajo por lotes?
Sí. Envía múltiples solicitudes de generación y recolecta los IDs de tarea, luego sondea en paralelo. Cada solicitud devuelve su propio task_id, por lo que los flujos de trabajo por lotes son sencillos: no necesitas esperar a que una termine antes de enviar la siguiente.
