La API pública de Picverce AI para desarrolladores

La API tiene una sola idea en el centro. Creas un trabajo, responde al momento y vuelves más tarde a por el resultado.

Todo lo demás en la documentación de la API pública se deriva de esa decisión, incluido cómo se cobran los créditos y cómo se comportan los reintentos.

Esta es su forma antes de que escribas una línea de código.

Cada trabajo es asíncrono a propósito

Envías un trabajo y recibes respuesta enseguida con estado en cola. El proceso sigue después de que la respuesta se cierre.

Después consultas el trabajo por su identificador hasta que informa de que terminó o falló.

Ese diseño existe para que un modelo lento nunca se convierta en un tiempo de espera agotado de tu lado. Una petición que espera a que se pinte una imagen es una petición que muere en algún proxy a los noventa segundos.

Te cuesta un viaje de ida y vuelta más y te compra un cliente que no se rompe cuando un modelo tiene un mal día.

Si no quieres consultar en bucle, puedes registrar una dirección y que te avisen cuando un trabajo termine. Eso se configura en tu cuenta y no a través de la API.

Cuando monté esto por primera vez hice el bucle con un intervalo fijo de un segundo y funcionó bien. Cualquier cosa más lista que eso es una optimización que puedes añadir luego.

Qué puedes llamar de verdad

Detrás del mismo punto final conviven dos familias de trabajo, y eliges entre ellas con un campo de tipo.

• Los trabajos de herramienta ejecutan una herramienta de imagen sobre un archivo que aportas.
• Los trabajos de generación crean una imagen nueva desde una descripción y un modelo elegido.
• Hoy son ejecutables diecisiete herramientas, entre ellas mejorar, ampliar, restaurar, enfocar, colorizar, eliminar fondo, eliminar objetos, quitar marcas de agua, los conversores de anime, cartoon y boceto, peinado y outfit.
• Los puntos finales de catálogo listan lo disponible, así que nunca tienes que fijar la lista en el código.

Que una herramienta esté en el catálogo no significa que sea ejecutable por la API. Pide una que no lo sea y te dice cuáles sí lo son, por nombre, en lugar de un rechazo vago.

Leer el catálogo al arrancar en lugar de pegar la lista en tu código vale los cinco minutos. La lista crece.

Cuándo se cobran los créditos

Esta parte sorprende y es lo más amable de todo el diseño.

Los créditos se reservan al crear el trabajo y solo se cobran de verdad cuando termina bien.

Un trabajo que falla se devuelve entero e informa de cero cobrado. No estás pagando porque el modelo tuviera un mal día.

Los créditos reservados ya han salido de tu saldo disponible, y por eso una foto de tu cuenta puede verse más baja de lo que esperabas mientras hay trabajo en marcha.

La entrada se comprueba contra el catálogo antes de ejecutar nada. Una proporción o una resolución no admitida se rechaza con un error de validación que lista lo que sí se admite, en lugar de cambiarse en silencio por algo que no pediste.

Ese rechazo no cuesta nada. Un no claro es mejor que pagar por un resultado con la forma equivocada.

Claves, acceso y límites de uso

La autenticación es un token bearer. Tu clave va en la cabecera Authorization y en ningún otro sitio.

Las claves vienen en forma live y en forma test. Las dos se comportan igual, así que el prefijo de prueba es una comodidad de etiquetado para tu propio orden y no un entorno aislado.

Trata las dos como secretos. Una clave en JavaScript de navegador es una clave que cualquiera puede leer y con la que puede gastar tus créditos.

El acceso necesita un plan Basic, Standard o Premium activo, o cualquier paquete de créditos que hayas comprado. Una cuenta gratuita sin paquete puede leer la documentación pero no crear una clave.

Cada respuesta lleva tu situación de límite en las cabeceras, así que ves lo cerca que estás sin hacer una llamada extra. Si te pasas recibes un 429 y no un descarte silencioso.

Reintentar sin pagar dos veces

Las llamadas de red fallan a medias. La API tiene una respuesta concreta para eso en lugar de dejarte adivinar.

Envía una cabecera de idempotencia con un valor que elijas, normalmente un UUID, y la creación pasa a ser segura de repetir.

Una segunda petición con la misma cabecera y el mismo cuerpo devuelve el primer trabajo en lugar de arrancar otro, y no vuelve a cobrar. La respuesta te dice que fue una repetición.

Reutiliza la misma cabecera con un cuerpo distinto y recibes un conflicto, que es la API negándose a adivinar cuál querías.

Esos valores se recuerdan durante un día y están ligados a la clave que los usó.

Todo lo que ejecuta la API es el mismo proceso que ejecuta la web. Si quieres entender qué le hace un trabajo concreto a una foto antes de automatizarlo, empieza por Mejorador de Imágenes IA y mira pasar un archivo a mano.

El comportamiento por debajo es idéntico, incluidos los límites de archivo y los compromisos descritos en cómo funciona de verdad el Mejorador de Imágenes de Picverce AI.

Lee el catálogo, crea un trabajo, consúltalo y gestiona el fallo. Esa es toda la integración.