Guía de inicio de la API de texto a imagen recraft-v4.1-flash: capacidades, precios y mejores prácticas

Para quién es adecuado este modelo: límites de capacidad y posicionamiento en la selección

recraft-v4.1-flash/text-to-image es un modelo de generación de imágenes ofrecido por Recraft, cuyo tipo de salida es imagen y cuyo alcance de capacidad está claramente limitado a la ruta text-to-image. Su nombre incluye flash, y su posicionamiento es rápido y ligero; usarlo para generación de imágenes de alta frecuencia, bajo coste y con resultados suficientemente buenos es la expectativa más razonable.

Escenarios adecuados

• Tareas como generación masiva de materiales operativos, borradores de ilustraciones y miniaturas para redes sociales, donde no se exige un nivel extremo de detalle por imagen.
• Rellenos y demostraciones que requieren imágenes inmediatas en prototipos de producto o herramientas internas.
• Exploración A/B: generar por lotes varias variantes con el mismo prompt, ver primero la dirección y luego decidir si se refina.
• Etapas previas dentro del flujo de I+D, por ejemplo generar primero bocetos para selección humana y luego pasar a procesos posteriores de mayor coste.

Escenarios no adecuados

• Materiales comerciales que requieren renderizado preciso de texto y control complejo de maquetación: para estas necesidades conviene validar primero la estabilidad del modelo con texto y composición; si no es estable, cambiar a una solución específica.
• Tareas que requieren capacidades multimodales como edición de imágenes, repintado local o imagen a imagen: este modelo solo declara text-to-image, y las capacidades de edición quedan fuera de su alcance.
• Escenarios que exigen un límite mínimo de calidad muy alto en cada generación y que no pueden cubrirse con selección humana.

Criterio de selección

Divide la necesidad en tres dimensiones: «frecuencia de generación», «límite mínimo de calidad» y «si se necesita edición». Si la frecuencia es alta, el límite mínimo de calidad admite selección humana y no se necesita edición, se puede probar primero recraft-v4.1-flash; en caso contrario, conviene evaluar otros modelos de imagen. No lo trates como un modelo de imagen universal y todoterreno; su valor reside en completar de forma estable la conversión de texto puro a imagen con un coste por uso relativamente bajo.

Convenciones de interfaz que hay que confirmar antes de llamar

El error más habitual antes de integrar es escribir el cuerpo de la solicitud de memoria o por suposición. Los nombres de campos, valores de enumeración y estructuras de respuesta varían mucho entre modelos de imagen; se recomienda contrastar primero punto por punto con la documentación de interfaz unificada de HiAPI.ai y después escribir el código.

Qué comprobar a nivel de solicitud

• Método de autenticación: en qué cabecera se coloca la API Key y si hay una convención de prefijo.
• Identificador del modelo: el nombre del modelo en la solicitud debe coincidir exactamente con el nombre registrado recraft-v4.1-flash/text-to-image; no lo escribas ni lo abrevies por tu cuenta.
• Parámetros obligatorios y opcionales: confirma al menos el nombre del campo del prompt, la forma de pasar el tamaño/proporción de la imagen (si son números de ancho y alto o una enumeración predefinida) y si se puede configurar el número de imágenes por generación.
• Rango de valores de los parámetros: intervalo válido de tamaño, si admite ancho y alto personalizados y si, al salirse del rango, se devuelve error o se corrige automáticamente.
• Formato del cuerpo de la solicitud: si es JSON y cómo se establece la cabecera de tipo de contenido.

Qué comprobar a nivel de respuesta

• En qué forma se devuelve la imagen: URL o base64, y si la URL tiene período de validez; esto determina directamente si debes descargarla y transferirla de inmediato o guardar el enlace directamente en la base de datos.
• La ruta del campo donde se encuentra el resultado de imagen en la estructura de respuesta y si también se devuelve metainformación (como tamaño real y estado de generación).
• La estructura de la respuesta de error: correspondencia entre códigos de estado y códigos de error, para facilitar el tratamiento por categorías.

Una práctica útil

Primero ejecuta una vez con la solicitud mínima (solo parámetros obligatorios), imprime el texto completo de la respuesta, anota la ruta de los campos devueltos y luego añade parámetros gradualmente. Así evitas dificultades de diagnóstico por acumular parámetros de golpe y también descubres de antemano desviaciones entre la documentación y la realidad.

Facturación por imagen: cómo calcular el coste de $0.01/imagen

Este modelo factura por imagen, con un precio unitario de $0.01/imagen (los criterios en tiempo real y los precios más recientes se rigen por el panel de precios del sitio). La facturación por imagen se caracteriza porque el coste crece linealmente con el número de imágenes y no está directamente ligado a la longitud del prompt ni a la resolución, lo que simplifica la estimación de costes, pero también hace fácil subestimarlo en lotes y reintentos.

Primero calcula el coste nominal

Coste nominal = número de imágenes solicitadas × precio unitario por imagen. Por ejemplo, generar 4 imágenes de una vez cuesta 4 veces el precio unitario; un lote de 1000 imágenes cuesta 1000 veces el precio unitario. Este paso solo refleja las imágenes «generadas con éxito y adoptadas».

Después calcula el coste real

En el coste real hay dos incrementos que suelen pasarse por alto:

• Coste de reintentos: si las llamadas fallidas ya han generado facturación (por ejemplo, la solicitud se acepta pero el resultado no es utilizable), reintentar supone pagar de nuevo.
• Coste de descartes: la parte de las imágenes generadas en lote que se descarta en la selección humana y finalmente no entra en el producto también se incluye en la factura.

Por tanto, una fórmula más cercana a la realidad es: coste real ≈ (imágenes adoptadas con éxito + imágenes reintentadas + imágenes descartadas) × precio unitario. Si la tasa de aceptación es solo de la mitad, el coste equivalente por imagen se duplica; este es el indicador que más conviene cuantificar al estimar el presupuesto.

Cómo reducir el coste

• Haz primero pruebas por lotes pequeños, mide la tasa de aceptación del prompt y luego decide el tamaño del lote.
• La generación de varias variantes en una sola solicitud facilita más la selección humana que muchas solicitudes de una sola imagen y reduce los «reintentos a ciegas».
• Almacena en caché los resultados reutilizables para evitar facturar repetidamente el mismo prompt.
• Establece un límite de presupuesto para las tareas por lotes (convertido a número de imágenes) para evitar que reintentos anómalos agoten el presupuesto.

Flujo mínimo de integración utilizable

El objetivo es completar la primera generación exitosa por la ruta más corta y confirmar que toda la cadena (autenticación → solicitud → generación de imagen → almacenamiento) funciona sin obstáculos.

Paso uno: preparar credenciales

Crea una API Key en la consola de HiAPI.ai, guárdala en una variable de entorno y no la codifiques directamente en el repositorio. Confirma también el saldo disponible de la cuenta y los permisos de llamada.

Paso dos: construir la solicitud mínima

Incluye solo los campos obligatorios: el nombre del modelo recraft-v4.1-flash/text-to-image y el prompt. Usa un prompt concreto y sin ambigüedades, por ejemplo «un gato naranja de pie frente a un fondo blanco, vista frontal, luz suave».

curl -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft-v4.1-flash/text-to-image",
    "prompt": "un gato naranja de pie frente a un fondo blanco, vista frontal, luz suave"
  }'

La ruta real, las cabeceras de autenticación y los nombres de campos se rigen por la documentación de HiAPI.ai; lo anterior es solo un esqueleto ilustrativo.

Paso tres: analizar y almacenar

Lee la respuesta y obtén el resultado de imagen. Si es una URL, descárgala de inmediato y transfiérela a tu propio almacenamiento de objetos, registrando al mismo tiempo el prompt, los parámetros y la hora de generación para formar un registro de generación trazable.

Paso cuatro: validar la cadena

Confirma tres cosas: que el estado devuelto sea normal, que la imagen se abra correctamente y que el registro se haya escrito. Ejecuta de nuevo la misma solicitud y observa si se reproduce de forma estable; esto también valida el comportamiento en llamadas repetidas.

Mejores prácticas para prompts y parámetros

La incertidumbre en la generación de imágenes proviene de la combinación de prompt y parámetros; la práctica estable es estructurarlos, en lugar de escribir una frase improvisada cada vez.

Dividir el prompt en bloques

Organízalo en seis bloques: «sujeto + acción/estado + escena/fondo + composición y punto de vista + estilo + restricciones de calidad», eligiendo según necesidad:

• El sujeto y el estado determinan el núcleo de la imagen; sé lo más concreto posible («gato naranja» es mejor que «animal»).
• La composición y el punto de vista controlan el lenguaje visual («vista frontal», «cuerpo completo en encuadre»).
• Sé moderado con las palabras de estilo; acumular varias palabras de estilo contradictorias suele hacer el resultado menos controlable.

Ajusta solo los parámetros que tengan sentido

• Tamaño/proporción: alinéalos primero con la ubicación final de visualización del producto para evitar recortes masivos tras la generación. Si la documentación indica un intervalo válido, no envíes valores fuera de los límites.
• Número de imágenes: en la fase de exploración usa varias variantes para aumentar la tasa de acierto; una vez definido el estilo, reduce a una sola imagen para disminuir el coste de descartes.
• No envíes por suposición parámetros no confirmados en la documentación, para evitar errores o comportamientos impredecibles.

Gestiona los prompts como configuración

Convierte las plantillas de prompt validadas en plantillas variables (sujeto, escena y estilo sustituibles) y versiónalas en el código. Así puedes reutilizar combinaciones con alta tasa de aceptación y también rastrear «qué versión del prompt causó el problema». Ajusta solo una variable cada vez para poder determinar qué factor influyó en el resultado.

Estrategia de aceptación, caché y reintentos fallidos

El punto clave de ingeniería en las interfaces de generación no está en la llamada en sí, sino en el control de calidad de los resultados y el control de costes.

Aceptación: primero automática, luego humana

La capa automática realiza validaciones básicas: si la imagen se puede decodificar, si el tamaño cumple lo esperado y si está vacía o claramente anómala. Tras superar la capa automática, se pasa a muestreo o revisión humana completa (según el límite mínimo de calidad exigido). Se recomienda registrar la tasa de aceptación de cada lote como base para decidir el tamaño de lotes posteriores.

Caché: acierto por huella de entrada

Calcula una huella con «nombre del modelo + prompt + parámetros clave» como clave de caché. Si hay acierto, se reutiliza; solo si no lo hay se lanza la llamada. Es especialmente eficaz para estos dos casos:

• Solicitudes repetidas en entornos de desarrollo y pruebas.
• Materiales fijos reutilizados con alta frecuencia en producción.

La caché debe tener una política de expiración para que se refresque naturalmente cuando cambien las imágenes o se iteren los prompts.

Reintentos: acotados y distinguibles

• Reintenta solo errores reintentables (tiempos de espera agotados, errores temporales del servidor); reintentar errores de parámetros o fallos de autenticación no tiene sentido y solo duplica la facturación.
• Los reintentos deben tener un límite y retroceso, por ejemplo retroceso exponencial con un número máximo de intentos; si se supera, enviar a una cola de fallos para tratamiento humano.
• Antes de reintentar, determina si ya se ha generado un resultado utilizable, para evitar cargos duplicados por «en realidad tuvo éxito pero se marcó como fallo».

El principio que une los tres puntos es: lo que se puede cachear no se regenera, lo que se puede determinar no se reintenta y lo que se puede filtrar automáticamente no pasa a revisión humana.

Lista de comprobación antes del lanzamiento

Marcar cada punto antes de pasar a producción evita la mayoría de los problemas que solo se descubren después del lanzamiento.

Corrección

• El nombre del modelo recraft-v4.1-flash/text-to-image es coherente en código y configuración, sin variantes de escritura.
• Los parámetros de tamaño/proporción están dentro del rango permitido por la documentación y coinciden con la ubicación de visualización del frontend.
• La ruta de análisis de la respuesta se ha validado con una respuesta real, sin depender de suposiciones.
• La cadena de almacenamiento y acceso de los resultados de imagen (descarga, transferencia, CDN) está conectada.

Coste

• Se ha medido la tasa de aceptación real del prompt y, con base en ella, se ha estimado el coste equivalente por imagen válida.
• Las tareas por lotes tienen límite de presupuesto y límite de número de imágenes para evitar ampliaciones anómalas.
• La caché está activa y cuenta con monitorización de la tasa de aciertos.
• Los reintentos tienen límite de veces y estrategia de retroceso; no se reintenta de forma ilimitada.

Fiabilidad

• Los códigos de error están clasificados: reintentables / no reintentables / requieren intervención humana.
• La API Key va en variables de entorno y existe un plan de rotación y minimización de permisos.
• Los registros de generación son trazables (prompt, parámetros, hora, estado del resultado) para facilitar la revisión y la conciliación.
• Hay monitorización y alertas: volumen de llamadas, tasa de fallos, tasa de aceptación y anomalías de coste unitario pueden detectarse.

Una vez completada la lista, despliega primero con poco tráfico en modo gradual y observa si la tasa de aceptación real y la factura coinciden con lo estimado, y luego decide si ampliar la escala. Puedes consultar más detalles de la interfaz en la documentación del modelo de HiAPI.ai.