Qwen Image 3.0 API: precios e integración

Qwen Image 3.0 combina la generación de texto a imagen y la edición con imágenes de referencia en una sola API asíncrona. A través de APIMart, envías una tarea, consultas su estado y recuperas una o varias imágenes cuando finaliza.

Esta guía explica lo necesario antes de integrar: precios actuales de Standard y Pro, autenticación, parámetros, lectura de respuestas, sondeo, reintentos y almacenamiento. Para conocer las capacidades y los benchmarks, consulta la guía de lanzamiento de Qwen Image 3.0.

Precios y acceso a Qwen Image 3.0

APIMart ofrece dos identificadores de modelo:

• qwen-image-3.0 para Standard
• qwen-image-3.0-pro para Pro

La facturación se realiza por imagen generada, no por Token de entrada. La tabla refleja la página de precios de APIMart del 27 de agosto de 2026; los importes pueden cambiar.

Comparación de precios entre Standard y Pro

Standard tiene actualmente el mismo precio en 1K y 2K. Pro 2K cuesta el doble que Pro 1K. Según la documentación de Qwen Image 3.0, las generaciones fallidas se reembolsan y las imágenes de referencia no añaden un cargo de generación independiente.

Estimar un volumen de trabajo real

La fórmula básica es:

coste mensual = imágenes completadas × precio por imagen

n controla la cantidad de resultados, por lo que una solicitud con n: 4 puede facturar cuatro imágenes. Incluye en el presupuesto las pruebas de prompts, las variaciones y las regeneraciones.

Standard es adecuado para la mayoría de borradores y recursos habituales. Evalúa Pro cuando la mejora del texto, la composición o los detalles justifique el coste. Con Pro, utiliza 1K durante la iteración y reserva 2K para resultados finales de alta resolución.

Acceso y autenticación

Crea una cuenta de APIMart, añade saldo suficiente y genera una clave en la consola. Guarda la clave en un Secret o una variable de entorno del servidor; nunca la expongas en código del navegador ni en una variable NEXT_PUBLIC_*.

Base URL y Bearer Token

Los ejemplos utilizan esta Base URL:

https://api.apimart.ai/v1

Envía la clave como Bearer Token:

Authorization: Bearer <your_api_key>
Content-Type: application/json

Una clave ausente o inválida suele producir 401, el saldo insuficiente puede producir 402 y el límite de velocidad, 429. Registra la respuesta y el contexto en el servidor, pero oculta la clave antes de guardar los logs.

Generación, edición y flujo asíncrono

Tanto la generación como la edición usan POST /v1/images/generations. La API devuelve primero un ID de tarea en lugar de esperar a que termine la imagen.

Parámetros principales

En dimensiones personalizadas, cada lado debe medir entre 512 y 2.048 píxeles y la relación debe permanecer entre 1:8 y 8:1. Las referencias admiten JPEG, PNG, BMP, TIFF, WebP y GIF, con un límite documentado de 10 MB por imagen. Revisa la referencia de generación antes de publicar, ya que los límites pueden evolucionar.

El anuncio oficial de Qwen Image 3.0 describe renderizado de texto nativo en 12 idiomas. Pon entre comillas el texto que deba aparecer exactamente y valida ortografía, tipografía y composición en la resolución final.

Ejemplo de texto a imagen

{
  "model": "qwen-image-3.0",
  "prompt": "Un banner de producto limpio con el texto exacto \"Oferta de verano\", tipografía geométrica en negrita y fondo naranja cálido",
  "resolution": "1K",
  "size": "16:9",
  "n": 1,
  "prompt_extend": true
}

Ejemplo de edición con referencia

Añade image_urls para transformar una imagen existente:

{
  "model": "qwen-image-3.0-pro",
  "prompt": "Mantén intacta la forma del producto y sustituye el fondo por un estudio con iluminación suave",
  "image_urls": [
    "https://example.com/reference-product.png"
  ],
  "resolution": "2K",
  "n": 1
}

La URL de referencia debe ser accesible para la API. Para archivos privados, usa una URL firmada con validez suficiente para el envío y el procesamiento, o una Data URL compatible cuando resulte apropiado.

Flujo de tareas asíncronas

El flujo tiene tres pasos:

1. Envía una tarea con POST /v1/images/generations.
2. Lee data[0].task_id en la respuesta.
3. Consulta GET /v1/tasks/{task_id} hasta que termine o falle.

Respuesta al enviar

Una respuesta correcta tiene esta forma:

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}

No leas task_id del objeto superior: está en el primer elemento de data.

Sondeo y resultado final

Consulta cada tres a cinco segundos, en lugar de enviar solicitudes de estado sin pausa. Los archivos terminados aparecen en data.result.images:

{
  "code": 200,
  "data": {
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example-cdn.com/generated-image.png"
          ]
        }
      ]
    }
  }
}

La documentación actual indica que APIMart replica las imágenes terminadas en su CDN y las mantiene disponibles a largo plazo. Aun así, copia los recursos aprobados a un almacenamiento propio cuando necesites controlar retención, eliminación, acceso o rendimiento de entrega.

Ejemplos de integración

Integración con Python

Este ejemplo de servidor envía una tarea, consulta cada tres segundos y deja de esperar tras tres minutos:

import os
import time
import requests

API_KEY = os.environ["QWEN_API_KEY"]
BASE_URL = "https://api.apimart.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def generate_image(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=HEADERS,
        json={"model": "qwen-image-3.0", "prompt": prompt, "resolution": "1K", "n": 1, "prompt_extend": True},
        timeout=30,
    )
    response.raise_for_status()
    task_id = response.json()["data"][0]["task_id"]
    deadline = time.monotonic() + 180

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        task = poll.json()["data"]
        if task["status"] == "completed":
            return task["result"]["images"][0]["url"][0]
        if task["status"] == "failed":
            raise RuntimeError(task.get("fail_reason", "Generation failed"))
        time.sleep(3)

    raise TimeoutError(f"Task {task_id} did not finish within 180 seconds")

En una aplicación real, guarda la tarea antes de iniciar el sondeo. Si el Worker se reinicia, otro puede continuar la tarea guardada sin enviar y pagar una generación duplicada.

Integración con JavaScript

Ejecuta este código únicamente en un entorno de servidor de confianza:

const apiKey = process.env.QWEN_API_KEY;
const baseUrl = "https://api.apimart.ai/v1";
const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };

async function requestJson(url, options = {}) {
  const response = await fetch(url, { ...options, headers });
  const payload = await response.json();
  if (!response.ok) throw new Error(`APIMart ${response.status}: ${JSON.stringify(payload)}`);
  return payload;
}

async function generateImage(prompt) {
  const submission = await requestJson(`${baseUrl}/images/generations`, {
    method: "POST",
    body: JSON.stringify({
      model: "qwen-image-3.0", prompt, resolution: "1K", n: 1, prompt_extend: true,
    }),
  });
  const taskId = submission.data[0].task_id;
  const deadline = Date.now() + 180_000;

  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    const { data: task } = await requestJson(`${baseUrl}/tasks/${taskId}`);
    if (task.status === "completed") return task.result.images[0].url[0];
    if (task.status === "failed") throw new Error(task.fail_reason ?? "Generation failed");
  }
  throw new Error(`Task ${taskId} did not finish within 180 seconds`);
}

También puedes probar el flujo con cURL:

curl -X POST https://api.apimart.ai/v1/images/generations \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-image-3.0","prompt":"Una fotografía minimalista de un producto","resolution":"1K","n":1}'

curl https://api.apimart.ai/v1/tasks/<task_id> \
  -H "Authorization: Bearer <your_api_key>"

Lista de comprobación para producción

Una llamada correcta es solo el principio. Una canalización fiable también necesita reintentos limitados, estado persistente, observabilidad y almacenamiento controlado.

Errores y política de reintentos

No vuelvas a enviar una generación a ciegas después de un timeout ambiguo. Si el servidor aceptó la primera solicitud, la segunda puede crear una tarea duplicada y otro cargo. Guarda cada ID y separa los reintentos de envío de los reintentos de sondeo.

Antes del lanzamiento

• Guarda la clave únicamente en un Secret del servidor.
• Valida prompt, resolution, size, n y las referencias antes de enviar.
• Conserva el ID y el estado de la tarea.
• Consulta cada tres a cinco segundos y establece un timeout de aplicación.
• Aplica backoff exponencial con jitter a 429 y 5xx reintentables.
• Limita la concurrencia según las tasas y latencias observadas.
• Mide por separado tareas completadas, fallidas, agotadas y duplicadas.
• Copia los resultados aprobados a tu almacenamiento si necesitas controlar la retención.
• Antes de producción, revisa de nuevo la página del modelo Qwen Image 3.0, los precios y la documentación.

Genera imágenes con Qwen Image 3.0

Prueba Standard y Pro con la API unificada de APIMart, compara resultados en 1K y 2K y lleva tu flujo de imágenes del prototipo a producción.

Explorar Qwen Image 3.0

Preguntas frecuentes

¿Cuánto tiempo debo consultar antes del timeout?

APIMart recomienda consultar cada tres a cinco segundos y sugiere unos tres minutos de timeout en el cliente. Úsalo como punto de partida, mide la latencia real y conserva el ID para poder reconciliar después las tareas agotadas.

¿Las URL de resultados caducan después de 24 horas?

La documentación actual indica que las salidas se replican en el CDN de la plataforma y permanecen disponibles a largo plazo. Por tanto, la antigua afirmación de 24 horas no se aplica a esta integración. Guarda los recursos críticos en infraestructura propia en lugar de depender de una retención externa sin plazo garantizado.

¿Puedo enviar una imagen de referencia en Base64?

Sí. La documentación actual permite entre una y tres URL públicas HTTP/HTTPS o Data URL Base64 compatibles en image_urls. Cada imagen debe cumplir los formatos admitidos y el límite de 10 MB.

¿Cuándo debo elegir 1K o 2K?

Usa 1K para iteraciones rápidas y recursos que no exijan el máximo detalle. Elige 2K para imágenes finales con mucho texto, bordes finos o visualización a gran tamaño. Standard tiene actualmente el mismo precio en ambas resoluciones, mientras Pro 2K cuesta más que Pro 1K; valora juntos latencia, calidad y coste.