Crea una clave de API y lanza tu primer trabajo

Este es el camino más corto de la nada a un trabajo terminado. Cuatro pasos, y el tercero es el que todo el mundo falla la primera vez.

Comprueba que puedes crear una clave

El acceso no viene con el plan gratuito por sí solo. Necesitas un plan Basic, Standard o Premium activo, o cualquier paquete de créditos comprado.

Un paquete de créditos es la vía más barata si solo quieres probar. Comprar uno desbloquea la creación de claves en una cuenta por lo demás gratuita.

Las claves viven en la pestaña API de tu cuenta, junto a tu uso y tus direcciones de aviso.

Crea una y cópiala al momento. Trátala como tratarías una contraseña, porque es exactamente eso.

Verás un prefijo live y uno test disponibles. Los dos se comportan igual y los dos gastan créditos reales, así que el de prueba es una etiqueta para tu organización y no un entorno gratis.

Envíala como token bearer

La clave va en la cabecera Authorization como token bearer. No en la cadena de consulta, ni en una cabecera propia, y nunca en código que llegue a un navegador.

Una llamada rápida al punto final de resumen de cuenta es la forma más veloz de confirmar que la clave funciona antes de construir nada encima.

Esa llamada muestra además tu saldo y tu situación de límite, y leerla no consume nada de ese límite.

Hazlo antes de escribir nada más. Un problema de acceso descubierto en el paso uno es un minuto perdido, y el mismo problema descubierto dentro de un bucle es una tarde.

Crea el trabajo

Envía al punto final de trabajos un tipo, el identificador de herramienta o modelo, y la entrada de ese trabajo.

Recibes respuesta casi al momento con estado en cola y un identificador. La imagen no está lista y no se ha cobrado nada todavía.

Los créditos se reservan en este punto en lugar de gastarse. Salen de tu saldo disponible y vuelven si el trabajo falla.

Elige una herramienta barata para el primer intento. No hay razón para depurar tu primera integración contra un trabajo caro.

Lo que cuesta cada trabajo coincide exactamente con la web, y el precio por escala funciona igual que en Ampliador de Imágenes IA 2x 4x y 8x.

Consulta hasta que termine

Pide el trabajo por su identificador en bucle hasta que el estado deje de ser en cola o procesando.

Un intervalo de un segundo está bien para empezar. Cualquier cosa más lista es una optimización para cuando ya funcione.

• Para en el éxito y lee la salida.
• Para en el fallo y lee el error. Tus créditos ya han vuelto.
• Pon un techo al bucle para que un trabajo atascado no gire eternamente.
• No consultes más de una vez por segundo. Gastarás tu límite en nada.

Cuando escribí mi primer bucle olvidé el techo y lo dejé corriendo contra un trabajo que nunca resolvió. No se cobró nada, pero el proceso se quedó ahí hasta que me di cuenta.

Los dos errores que verás primero

Los dos son informativos en lugar de crípticos, lo que los hace rápidos de resolver.

El primero es un error de validación. Pediste una proporción, una resolución o un número de variaciones que la herramienta no admite, y la respuesta lista lo que sí admite.

No se cobra nada ni se altera nada en silencio. La alternativa sería pagar por un resultado con una forma que no pediste.

El segundo es una herramienta que existe en el catálogo pero todavía no es ejecutable por la API. El error nombra las que sí lo son, así que puedes elegir una del propio mensaje.

Lee los puntos finales de catálogo al arrancar en lugar de fijar una lista, y ese segundo error deja de aparecer.

Un tercer error que conviene esperar es la comprobación de plan. Si tu acceso caduca, las llamadas empiezan a rechazarse con un mensaje que apunta a precios en lugar de fallar de forma oscura.

Ninguno de los tres cuesta créditos. Los errores se rechazan antes de que empiece ningún trabajo.

Haz seguros los reintentos antes de publicar

Es un cambio de cinco minutos que evita un problema real más adelante.

Envía una cabecera de idempotencia en la creación, con un valor que generes por trabajo lógico. Un UUID es la opción más simple.

Si la llamada falla a medias y la repites con el mismo valor y el mismo cuerpo, recuperas el trabajo original en lugar de un segundo, y no te cobran dos veces.

Reutiliza el mismo valor con otro cuerpo y recibes un conflicto, que es la API negándose a adivinar. Esos valores se recuerdan durante un día.

La referencia completa de parámetros de cada herramienta está en la documentación de la API pública, incluidas las opciones que acepta cada una.

Clave, creación, consulta y gestión del fallo. Acierta en esos cuatro y lo demás es elegir qué herramienta llamar.