- Cuándo usar este inicio rápido
- Paso 1: Obtenga su clave API de Novita
- Paso 2: Confirme el endpoint y el modelo
- Paso 3: Envíe su primera solicitud
- Paso 4: Sondee para obtener su resultado
- Ejemplo en Python: De extremo a extremo
- Ejemplo en cURL
- Parámetros clave
- Lo que Qwen Image genera bien
- Errores comunes y soluciones
- Preguntas frecuentes
- Artículos recomendados
La API de texto a imagen de Qwen Image en Novita AI genera imágenes a partir de indicaciones textuales utilizando el modelo Qwen Image de 20B — la misma base que impulsa la API de edición de 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 completar y recuperar la URL de la imagen. El endpoint es POST https://api.novita.ai/v3/async/qwen-image-txt2img.
Cuándo usar este inicio rápido
Use esta guía cuando necesite:
- Generar imágenes a partir de indicaciones 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, recursos 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 estilizado incrustado en la salida — piensa en pósters, carteles, maquetas de productos y gráficos de portada. Si su caso de uso implica editar una imagen existente en lugar de generar desde cero, consulte la API de edición de Qwen Image en su lugar. Si desea una visión general completa de las capacidades y benchmarks del modelo Qwen Image, el artículo de lanzamiento de Qwen Image de Novita AI cubre la arquitectura y los resultados de los benchmarks en detalle.
Paso 1: Obtenga su clave API de Novita
Cree una cuenta en Novita AI y navegue a Administración de claves API. Genere una clave y guárdela como variable de entorno:
export NOVITA_API_KEY="your_api_key_here"
Mantenga la clave fuera del código del lado del cliente, los bundles del frontend y el control de versiones.
Paso 2: Confirme el endpoint y el modelo
| Elemento | Valor |
|---|---|
| Endpoint de generación | POST https://api.novita.ai/v3/async/qwen-image-txt2img |
| Endpoint de sondeo de resultado | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| Modelo | Qwen Image (20B MMDiT) |
| Documentación API | Referencia de Qwen Image txt2img de Novita AI |
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; usted sondea el endpoint de resultado 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. Verifique la tarifa actual en la página de precios de Novita AI antes de hacer una estimación de costos.
Paso 3: Envíe su primera solicitud
Haga 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 exitosa 200 devuelve:
{
"task_id": "abc123..."
}
Guarde el task_id. Lo usará en el siguiente paso.
Paso 4: Sondee para obtener su resultado
Haga 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. Siga 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"
}
]
}
El image_url es una URL con límite de tiempo — el valor image_url_ttl (en segundos) le indica cuánto tiempo sigue siendo válida. Descargue la imagen rápidamente o póngala a través de su propio almacenamiento si necesita acceso a largo plazo.
Valores de estado a manejar:
| Estado | Significado |
|---|---|
TASK_STATUS_QUEUED |
La solicitud está en cola, aún no iniciada |
TASK_STATUS_PROCESSING |
Generación en progreso |
TASK_STATUS_SUCCEED |
La imagen está lista; lea images[0].image_url |
TASK_STATUS_FAILED |
Generación fallida; verifique task.reason |
Ejemplo en Python: De extremo a extremo
Este script envía una solicitud de generación, sondea hasta completar 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 en 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: Sondee 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 | Requerido | Predeterminado | 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. Enfóquese en que su indicación describa lo que debe contener la imagen y su estilo visual.
Lo que Qwen Image genera bien
La arquitectura 20B MMDiT 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 vuelven borrosas, las letras se intercambian y los diseños de varias líneas colapsan. Qwen Image maneja el texto en inglés y chino con una precisión notablemente mejor. Los pósters, carteles, etiquetas y gráficos con subtítulos son casos de uso viables en lugar de una incertidumbre.
Consistencia semántica. Cuando una indicación 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 otras arquitecturas más pequeñas o antiguas.
Seguimiento de indicaciones a gran escala. Indicaciones largas y detalladas que describen múltiples atributos — escena, iluminación, estilo, paleta de colores, objetos específicos — producen resultados que reflejan la indicación completa en lugar de aferrarse a una palabra clave.
Donde es menos adecuado: flujos de trabajo de generación en tiempo real o interactivos. El patrón asíncrono significa que hay latencia inherente entre la solicitud y el resultado. Si su caso de uso requiere retroalimentación en menos de un segundo, este endpoint no es la opción adecuada.
Errores comunes y soluciones
401 No autorizado: Verifique que el encabezado Authorization tenga el formato Bearer <key> con un espacio después de Bearer. Confirme que la clave esté activa en la consola de Novita AI.
400 Solicitud incorrecta en size: El parámetro size debe usar * como separador (ej., 1024*1024), no x, ×, ni un arreglo JSON. Cada dimensión debe estar entre 256 y 1536.
TASK_STATUS_FAILED sin motivo: Generalmente causado por una indicación que activa el filtrado de contenido. Simplifique la indicación y vuelva a intentarlo. Evite indicaciones 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 le indica cuánto tiempo es válida la URL. Descargue la imagen inmediatamente después de que el sondeo tenga éxito, o guárdela en su propio almacenamiento de objetos.
Sondeo lento: El tiempo de generación varía según la carga del servidor. Comenzar el sondeo con intervalos de 2 segundos es razonable. Si la tarea sigue en TASK_STATUS_QUEUED después de 10 segundos, continúe sondeando — la profundidad de la cola puede aumentar durante el uso pico.
Preguntas frecuentes
¿Hay 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 necesita generación de imágenes compatible con OpenAI, Novita AI ofrece modelos FLUX y SDXL a través de endpoints compatibles — consulte la documentación de Novita AI.
¿Cuál es la diferencia entre este endpoint y el endpoint de edición de Qwen Image?
Este endpoint genera imágenes solo a partir de una indicación textual — no se necesita una imagen de entrada. El endpoint de edición de Qwen Image toma una imagen existente más una instrucción de texto y modifica la imagen en consecuencia. Use txt2img cuando esté creando desde cero; use edit cuando necesite cambiar algo en una imagen existente.
¿El modelo soporta relaciones de aspecto distintas a la cuadrada?
Sí. Use el parámetro size para establecer el ancho y alto de forma independiente en cualquier lugar entre 256 y 1536 píxeles por dimensión. Las proporciones altas (ej., 1024*1536) funcionan bien para contenido vertical; las proporciones anchas (ej., 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 necesita resultados reproducibles, guarde la URL de la imagen inmediatamente y almacene la imagen en su propio almacenamiento en lugar de volver a generarla.
¿Puedo usar esta API en un trabajo por lotes?
Sí. Envíe múltiples solicitudes de generación y recoja los IDs de tarea, luego sonderéelos en paralelo. Cada solicitud devuelve su propio task_id, por lo que los flujos de trabajo por lotes son sencillos — no necesita esperar a que una termine antes de enviar la siguiente.
