Una guía práctica de la API de PicassoIA: la URL base, los cuatro modelos de imagen y video, cómo funcionan hoy los precios y los requisitos de plan, cómo crear y proteger un token de API, peticiones funcionales en cURL, Python y Node, y los límites que condicionan tu diseño.
Si has buscado una API de Picasso AI, probablemente quieres tres respuestas antes de escribir código: cuánto cuesta, cómo te autenticas y qué puedes llamar según la documentación. En resumen: PicassoIA ofrece una API REST de estilo Replicate en https://api.picassoia.com/v1, se autentica con un token bearer que empieza por pia_sk_, expone cuatro modelos para imágenes y video, y su documentación indica que las predicciones de la API son gratis por ahora. La letra pequeña es un requisito de plan, y conviene leerlo antes de construir nada encima. Este artículo sigue el orden en que te encontrarás las cosas en la práctica: precios, configuración de credenciales, tu primera petición, los límites, el video y el conector MCP que comparte los mismos cuatro modelos.
La página de la API de PicassoIA describe un alcance pequeño y concreto. Envías una petición para crear una predicción, el trabajo se ejecuta en las GPU propias de PicassoIA y consultas hasta que el resultado está listo. No hay SDK que instalar, y los ejemplos de código de la documentación usan HTTP sencillo en cURL, Python y Node.
Todas las llamadas van a una sola URL base y llevan una sola cabecera:
Base URL: https://api.picassoia.com/v1
Header: Authorization: Bearer pia_sk_...
Content-Type: application/json
El prefijo pia_sk_ marca un token secreto. Trátalo como una contraseña, porque cualquiera que lo tenga puede gastar la capacidad de tu plan.
El catálogo web incluye más de 250 modelos de imagen, video y chat. La API expone cuatro de ellos:
| ID del modelo | Página del modelo | Qué hace | Salida |
|---|---|---|---|
picassoia/picassoia-image | PicassoIA Image | Texto a imagen, 1 o 2 imágenes por llamada | Lista de URL de imágenes |
picassoia/picassoia-image-editor-pro | PicassoIA Image Editor Pro | Edita o combina de 1 a 4 imágenes de entrada | Lista de URL de imágenes |
picassoia/picassoia-video | PicassoIA Video | Texto o imagen a video | Una URL de MP4 |
picassoia/seedance-2.5-lite | Seedance 2.5 Lite | Texto o imagen a video con audio sincronizado | Una URL de MP4 |
💡 Conviene saber: la referencia de la API también ofrece
GET /v1/models, que devuelve cada modelo con su esquema de entrada. Léelo una vez en lugar de adivinar los nombres de los parámetros a partir de los ejemplos.
| Método y ruta | Función |
|---|---|
POST /v1/models/{owner}/{name}/predictions | Crear una predicción |
GET /v1/predictions/{id} | Consultar el estado y leer el resultado |
POST /v1/predictions/{id}/cancel | Cancelar una predicción en curso |
GET /v1/predictions | Listar predicciones, 50 por página, de la más reciente a la más antigua |
GET /v1/models | Listar modelos con sus esquemas |
Cuatro modelos y cinco ranuras encajan con un tipo concreto de proyecto. Funciona bien para flujos de contenido que convierten una hoja de cálculo con nombres de productos en imágenes para banners, para pequeñas apps que añaden un botón de "crear una imagen", para equipos editoriales que necesitan un flujo constante de imágenes de cabecera y bucles de video cortos, y para scripts que se ejecutan de noche mientras nadie espera. Encaja peor si necesitas un modelo de terceros concreto, un endpoint de chat o cientos de usuarios simultáneos, porque el techo es por cuenta y la lista de modelos es fija.
La documentación lo dice claramente: "Las predicciones de la API son gratis por ahora. No usan créditos." Eso elimina la aritmética habitual por llamada. La mayoría de las API alojadas de imagen y video cobran por llamada o por segundo de salida, así que un bug en un bucle cuesta dinero. Aquí, el mismo bug te cuesta rendimiento, por el límite de cinco predicciones que se describe más abajo.
La letra pequeña está en el plan. Según la referencia de la API, se necesita un plan Infinite para crear predicciones. Leer, listar y cancelar funciona sin él, así que puedes probar tu token y el código de tu cliente en un plan inferior, pero la primera POST que crea un trabajo necesita Infinite.
La página de precios añade una segunda señal. Lista API Access y MCP Connections como funciones de los planes de pago (Pro+, Elite e Infinite), cada una con una etiqueta "New", pero no dice nada sobre si las llamadas a la API consumen créditos. Así que tienes dos afirmaciones que no encajan del todo:
| Fuente | Qué dice |
|---|---|
| Página de la API | Las predicciones son gratis y no usan créditos; se necesita Infinite para crearlas |
| Página de precios | API Access y MCP Connections aparecen en los tres planes de pago; sin detalles sobre créditos |
💡 Regla práctica: toma la página de la API como referencia para crear predicciones y luego confírmalo en tu propia cuenta antes de prometer nada a un cliente. Los precios de los planes cambian, así que consulta el precio actual de Infinite en la página de precios en lugar de fiarte de una cifra copiada en un artículo.
Como la palabra "por ahora" aparece en la documentación, diseña tu integración para que se pueda añadir un costo más adelante: registra desde el primer día el ID de cada predicción, el modelo y el tamaño de la salida. Si la facturación llega algún día, ya tendrás los datos de uso.
pia_sk_.Cada cuenta puede tener como máximo 2 tokens. Ese límite parece estrecho, pero encaja con un hábito de rotación limpio que se explica a continuación.
Guarda el token en una variable de entorno y léelo en tiempo de ejecución. Los ejemplos de abajo usan PICASSOIA_API_TOKEN, un nombre elegido para este artículo, no uno que la plataforma exija.
.env a tu archivo de exclusiones y revisa los commits antiguos si alguna vez se te escapó.
💡 Antes de copiar nada: la API sigue el patrón de Replicate, así que los ejemplos usan los nombres de campo que ese patrón implica (
id,status,output). Imprime una vez la primera respuesta que recibas y comprueba esos nombres antes de llevar esto a producción.
export PICASSOIA_API_TOKEN="pia_sk_your_token_here"
curl -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions \
-H "Authorization: Bearer $PICASSOIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": {"prompt": "a lighthouse at sunset", "aspect_ratio": "16:9"}}'
La llamada devuelve enseguida un objeto de predicción. La imagen todavía no existe: el trabajo queda en cola y se ejecuta de forma asíncrona.
curl https://api.picassoia.com/v1/predictions/PREDICTION_ID \
-H "Authorization: Bearer $PICASSOIA_API_TOKEN"
Repite la consulta cada pocos segundos hasta que el estado sea succeeded o failed. Un fallo es definitivo, así que vuelve a enviar una nueva predicción en lugar de esperar. Cuando tiene éxito, la salida contiene las URL de las imágenes. Guarda los archivos que te importen en tu propio almacenamiento en lugar de enlazar directamente las URL de resultado.
Registra el cuerpo completo de la respuesta siempre que una predicción falle, junto con el prompt y el ID del modelo. La mayoría de los fallos se deben a un prompt demasiado largo, una imagen demasiado grande o un objeto input mal formado, y la respuesta guardada te dice cuál en segundos. Añade tu propio tiempo máximo, por ejemplo dos minutos para una imagen y diez para un video, y luego llama al endpoint de cancelación para que un trabajo atascado no ocupe una de tus cinco ranuras.
import os, time, requests
BASE = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_TOKEN']}"}
def generate(prompt):
r = requests.post(
f"{BASE}/models/picassoia/picassoia-image/predictions",
json={"input": {"prompt": prompt, "aspect_ratio": "16:9"}},
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
prediction = r.json()
while prediction["status"] not in ("succeeded", "failed", "canceled"):
time.sleep(3)
prediction = requests.get(
f"{BASE}/predictions/{prediction['id']}", headers=HEADERS, timeout=30
).json()
return prediction
const BASE = "https://api.picassoia.com/v1";
const headers = {
Authorization: `Bearer ${process.env.PICASSOIA_API_TOKEN}`,
"Content-Type": "application/json",
};
export async function generate(prompt) {
const res = await fetch(`${BASE}/models/picassoia/picassoia-image/predictions`, {
method: "POST",
headers,
body: JSON.stringify({ input: { prompt, aspect_ratio: "16:9" } }),
});
let prediction = await res.json();
while (!["succeeded", "failed", "canceled"].includes(prediction.status)) {
await new Promise((r) => setTimeout(r, 3000));
prediction = await (await fetch(`${BASE}/predictions/${prediction.id}`, { headers })).json();
}
return prediction;
}
| Límite | Valor |
|---|---|
| Predicciones en cola o en ejecución | 5 por cuenta, compartidas entre todos los tokens y conexiones MCP |
| Cuerpo de la petición | 10 MB como máximo |
| Imágenes en data URL | 5 MB cada una como máximo |
| Longitud del prompt | 4000 caracteres como máximo |
| Tokens por cuenta | 2 |
| Página de la lista de predicciones | 50 elementos, de la más reciente a la más antigua |
El techo es por cuenta, no por token. Si una tarea cron, una aplicación web y una sesión MCP se ejecutan a la vez, todos consumen las mismas cinco ranuras. Pon un limitador delante de tu cliente, como un semáforo o un grupo de cinco procesos de trabajo, y encola el resto tú mismo.
El rendimiento es fácil de estimar. Si una predicción de imagen tarda N segundos desde el envío hasta succeeded, cinco ranuras te dan aproximadamente 5 / N imágenes por segundo, y un lote de 500 imágenes tarda unos 500 × N / 5 segundos. Mide N en tus primeras diez llamadas y dimensiona los lotes nocturnos con ese número en lugar de con una suposición. Los trabajos de video tardan más, así que ejecútalos en su propia cola y reserva una o dos ranuras para las imágenes.
Tres errores aparecen una y otra vez:
POST simultáneas significan cuarenta y cinco rechazadas o atascadas.
Un prompt puede llegar a 4000 caracteres, espacio más que suficiente para los prompts largos y detallados que necesita el trabajo fotorrealista. La restricción más ajustada es la entrada de imágenes. Cada imagen en data URL puede llegar a 5 MB, pero el cuerpo completo de la petición tiene un tope de 10 MB, así que cuatro imágenes cercanas al límite en una misma llamada de edición no caben. Reduce el ancho a un tamaño razonable y comprime a JPEG antes de codificar.
PicassoIA Video acepta texto o una imagen y devuelve un único MP4. La referencia vincula la duración máxima a la resolución:
| Resolución | Duración máxima |
|---|---|
| 480p | 20 segundos |
| 720p | 10 segundos |
| 1080p | 5 segundos |
Elige la resolución más baja que cumpla el encargo. Un borrador a 480p te da cuatro veces la duración de un render a 1080p, lo que va bien para bucles de redes sociales y storyboards. Los trabajos de video tardan más que los de imagen, así que consulta cada 8 a 10 segundos, no cada 3.
Seedance 2.5 Lite añade audio sincronizado al clip, lo que ahorra un paso de sonido aparte. La referencia de la API indica duraciones de 5, 10 y 15 segundos, mientras que el catálogo web describe clips de hasta 10 segundos, así que lee el esquema de GET /v1/models antes de fijar en el código un valor permitido. El Seedance 2.5, el de mayor tamaño, sigue en el catálogo del navegador y no forma parte de la API.
El conector MCP ofrece a los asistentes de IA los mismos cuatro modelos sin necesidad de código HTTP. El conector de claude.ai expone herramientas para generar imágenes, editar imágenes, crear video con cualquiera de los dos modelos de video y gestionar trabajos: generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, list_generations, list_models, get_account y cancel_generation.
El flujo replica el de REST. Una herramienta de generación devuelve un ID de predicción y un tiempo estimado en cuanto una GPU acepta el trabajo. Después llamas a get_generation tras la demora sugerida, y de nuevo tras cada demora que devuelva, hasta que el estado sea succeeded o failed. cancel_generation detiene un trabajo que todavía no ha empezado a renderizarse. La concurrencia es la misma, las cinco ranuras compartidas.
Los modelos de chat son otra cuestión. Ninguno de los cuatro modelos de la API escribe texto, así que los modelos de lenguaje están en el navegador: Claude Sonnet 5 para redactar textos largos, GPT 5.6 Sol para problemas de programación difíciles y Gemini 3.5 Flash cuando la velocidad importa. Un buen flujo es redactar y pulir un prompt con uno de ellos y luego pegar el resultado en tu llamada a la API. Modelos como GPT Image 2, Flux 2 Pro, Veo 3.1 y Kling v3 Video también están solo en el catálogo del navegador.
Prueba cada prompt en el navegador antes de automatizarlo. Un prompt malo no cuesta nada allí, y las mismas ideas pasan directamente a la llamada a la API.
16:9 va bien para banners y cabeceras de blog, 1:1 para las tarjetas de producto. La API usa el mismo campo aspect_ratio.| Parte del prompt | Ejemplo |
|---|---|
| Sujeto | Un panadero sacando hogazas de un horno de piedra |
| Escenario | Una panadería de pueblo estrecha al amanecer |
| Luz | Luz cálida de ventana desde la izquierda |
| Objetivo | 50mm f/1.8, profundidad de campo reducida |
| Textura | Polvo de harina, corteza agrietada, delantal de lino |
¿Listo para probarlo tú? Abre PicassoIA Image, escribe el prompt que habrías enviado en tu primera llamada a la API y mira cómo se renderiza. Cuando el resultado te convenza, copia el mismo prompt en el ejemplo de cURL de arriba y deja que tu propio código haga el resto. Si quieres explorar todo lo demás que puede hacer la plataforma, el catálogo completo de modelos está a un clic.
Elige tu idioma
