Usa Picverce AI desde tu propio servidor

Dos formas de usarla

Ambas pasan por el mismo endpoint. Si ya tienes la imagen y quieres cambiarla, eso es una Herramienta. Si quieres una imagen que aun no existe, eso es un Modelo.

Inicio rapido

1. 1. Crea una clave

   Ve a Cuenta, Claves de API y pulsa Crear clave. El secreto se muestra una sola vez y no se puede recuperar, asi que copialo antes de cerrar el dialogo.

   Las claves son del tipo pk_live_.... Una clave pk_test_ funciona igual y es para desarrollo.

   El acceso a la API publica viene con un plan de pago o un paquete de creditos. Una suscripcion activa Basic, Standard o Premium lo incluye, y tambien cualquier paquete de creditos que hayas comprado. Ver planes

2. 2. Consulta tu saldo

   curl https://api.picverce.com/v1/me \
     -H "Authorization: Bearer pk_live_..."

3. 3. Crea un trabajo

   curl -X POST https://api.picverce.com/v1/jobs \
     -H "Authorization: Bearer pk_live_..." \
     -H "Content-Type: application/json" \
     -d '{
       "type": "tool",
       "tool": "background_remover",
       "input": { "image_url": "https://example.com/product.jpg" }
     }'

   Responde en milisegundos con status: "queued" y un id de trabajo.

4. 4. Consulta hasta que termine

   curl https://api.picverce.com/v1/jobs/JOB_ID \
     -H "Authorization: Bearer pk_live_..."

   Consulta cada par de segundos hasta que status diga succeeded o failed. Los resultados llegan en output.images.

Lo mismo en JavaScript

Node 18 o superior. Ejecutalo en tu servidor, nunca en un navegador.

const KEY = process.env.PICVERCE_API_KEY;
const BASE = 'https://api.picverce.com';

async function api(path, options = {}) {
  const response = await fetch(BASE + path, {
    ...options,
    headers: {
      Authorization: `Bearer ${KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  const body = await response.json();
  if (!response.ok) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }
  return body;
}

async function runJob(payload) {
  const job = await api('/v1/jobs', { method: 'POST', body: JSON.stringify(payload) });

  while (true) {
    const current = await api(`/v1/jobs/${job.id}`);
    if (current.status === 'succeeded') return current.output.images;
    if (current.status === 'failed') throw new Error(current.error.message);
    await new Promise((r) => setTimeout(r, 2000));
  }
}

const images = await runJob({
  type: 'generate',
  model: 'flux-schnell',
  input: { prompt: 'a red bicycle against a white wall' },
});

Herramientas que ya puedes ejecutar

Las 18 herramientas del catalogo aceptan trabajos. Los precios y los esquemas de entrada completos, incluidas las listas de presets de las tres que las usan, se consultan con GET /v1/tools, asi que una interfaz de ajustes se construye desde el catalogo y no desde esta pagina.

Los 26 modelos de generacion aceptan trabajos. Listalos con GET /v1/models y lee capabilities en vez de fijar proporciones y resoluciones en el codigo, porque cambian segun el modelo.

Opciones de las herramientas

Todas las herramientas reciben image_url y no requieren nada mas. Estos son los campos opcionales; cualquier herramienta que no aparezca aqui no acepta opciones. Un campo desconocido se rechaza por su nombre en lugar de ignorarse.

scale en upscale es la unica opcion que cambia el precio: 2 creditos a 2x, 3 a 4x y 6 a 8x. Todo lo demas cuesta lo que dice la tabla de arriba, pases lo que pases.

Claves de estilo

Las cuatro herramientas de redibujado reciben una clave style. Estas son las listas completas. Las claves van en minusculas, y una clave que esta API no conoce se rechaza con un 422 que nombra las admitidas, en lugar de redibujar en el estilo por defecto sin avisar.

{ "type": "tool", "tool": "colorize",
  "input": { "image_url": "https://example.com/photo.jpg" } }

{ "type": "tool", "tool": "photo_to_sketch",
  "input": { "image_url": "https://example.com/photo.jpg",
             "style": "charcoal-sketch" } }

{ "type": "tool", "tool": "face_restore",
  "input": { "image_url": "https://example.com/portrait.jpg",
             "upscale": 4, "codeformer_fidelity": 0.8,
             "face_upsample": true, "background_enhance": false } }

Las tres que reciben algo mas que una imagen

Los valores de preset son cadenas exactas, y las listas completas son enums en GET /v1/tools/{id}. Son nombres, no slugs: es Smart casual, nunca smart-casual. Un valor desconocido devuelve un 422 que nombra los admitidos.

object_remover recibe una segunda imagen en mask_url, del mismo tamano que la original: el blanco marca lo que se borra y el negro lo que se conserva. Las dos URLs se descargan y se comprueban igual, asi que una mascara en una direccion privada se rechaza como cualquier otra.

hairstyle recibe un preset por trabajo. El sitio web puede aplicar varios a la vez; la API no, y un valor separado por comas se rechaza en lugar de interpretarse. outfit admite hasta tres colores, y outfit_color_count decide cuantos se usan. Los alcances top y bottom solo tienen dos zonas, asi que ahi un 3 se comporta como 2.

{ "type": "tool", "tool": "object_remover",
  "input": { "image_url": "https://example.com/room.jpg",
             "mask_url": "https://example.com/room-mask.png" } }

{ "type": "tool", "tool": "hairstyle",
  "input": { "image_url": "https://example.com/portrait.jpg",
             "haircut": "Blunt Bangs", "hair_color": "Auburn" } }

{ "type": "tool", "tool": "outfit",
  "input": { "image_url": "https://example.com/portrait.jpg",
             "outfit": "Smart casual", "garment_scope": "full",
             "outfit_color": "Navy", "outfit_color_2": "Cream",
             "outfit_color_count": 2 } }

Ajustes de generacion

Un trabajo de generacion recibe un id de modelo y estos seis campos. No se acepta nada mas, y un nombre de campo parecido pero incorrecto se rechaza en lugar de ignorarse: es ratio, no aspect_ratio, y variations, no n.

Lo que admite cada modelo cambia, asi que consulta GET /v1/models en lugar de fijar una lista en tu codigo. Las notas de abajo cubren lo que no se deduce de la respuesta de un solo modelo.

Creditos, y por que mas imagenes no cuestan mas

Un trabajo de generacion cuesta lo mismo pidas las variations que pidas. El precio lo fija solo resolution, y por eso el catalogo da a cada modelo un precio por resolucion en lugar de un unico numero. Cuatro imagenes a 1K cuestan lo que una imagen a 1K.

Los tokens de resolucion son propios de cada modelo y no son un tamano en pixeles. Unos usan 1K through 4K, otros usan 1 MP, 2 MP y 4 MP, y unos pocos usan Low, Medium, High o Auto. Lee capabilities.resolutions y credits.values juntos.

Proporciones

Hay tres conjuntos en el catalogo. Una proporcion que un modelo no admite devuelve un 422 que nombra las que si admite.

Hay un valor mas: match_input_image, que conserva la forma de tu imagen de referencia. Necesita a la vez un modelo cuyo capabilities.match_input_ratio sea true y un reference_image_url en la misma peticion. Hoy lo admiten 13 modelos.

Varias imagenes

No hay un endpoint de lote. Pedir mas de una imagen es variations en un trabajo normal, y el trabajo devuelve esa cantidad de URLs en output.images. La mayoria de los modelos se queda en 1. Hoy solo gpt-image-2 y chatgpt-1-5 llegan mas lejos, ambos a 4. Pasarse del limite de un modelo devuelve un 422 que lo nombra.

Imagenes de referencia y ayuda con el prompt

curl -s https://api.picverce.com/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $PICVERCE_API_KEY"

# capabilities.ratios          proporciones aceptadas
# capabilities.resolutions     tokens de resolucion aceptados
# capabilities.max_variations  tope de variations
# capabilities.reference_image unsupported | optional | required
# credits.values               precio por token de resolucion

{ "type": "generate", "model": "flux-schnell",
  "input": { "prompt": "a lighthouse in fog, 35mm" } }

{ "type": "generate", "model": "gpt-image-2",
  "input": {
    "prompt": "a lighthouse in fog, 35mm",
    "ratio": "3:2",
    "resolution": "High",
    "variations": 4
  } }

{ "type": "generate", "model": "nano-banana-2",
  "input": {
    "prompt": "the same room, repainted deep green",
    "reference_image_url": "https://example.com/room.jpg",
    "ratio": "match_input_image"
  } }

Los creditos se reservan al crear el trabajo y solo se cobran cuando termina bien. Un trabajo fallido se reembolsa por completo e informa credits.charged: 0.

Como los creditos se retienen por adelantado, tu saldo baja en cuanto creas un trabajo. GET /v1/me informa reserved_open para que veas cuanto retiene el trabajo que sigue en curso.

Errores

Todos los fallos tienen la misma forma, asi que un solo manejador los cubre todos.

{
  "error": {
    "code": "insufficient_credits",
    "message": "This job costs 6 credits and your balance is 2.",
    "request_id": "req_4f2a9c1b7e3d5a8c0b6e1f92"
  }
}

La entrada invalida se rechaza, no se corrige

Si pides una proporcion o un numero de variaciones que el modelo no admite, recibes un 422 con los valores admitidos. El sitio web sustituye en silencio por algo valido en esa situacion, lo cual esta bien cuando hay una persona mirando. Para un cliente automatico significaria pagar por una imagen que no pediste, asi que la API la rechaza.

Limites de peticiones

60 peticiones por minuto movil, por clave. Cuenta cada endpoint autenticado. Cada respuesta incluye tu situacion:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1787644920

Al pasarte recibes un 429 con Retry-After en segundos. Es una ventana movil, asi que 60 peticiones al inicio del minuto no te dan otras 60 un segundo despues.

Con honestidad sobre el tope: el contador funciona por instancia de borde, asi que el trafico repartido entre regiones puede superar algo las 60 en un minuto real. Disena para 60 en vez de apurarlo. Sera un limite global estricto en una version posterior.

Reintentos

Las lecturas se pueden repetir sin riesgo. Crear un trabajo no, salvo que lo indiques: dos creaciones son dos trabajos y dos cobros. Envia una cabecera Idempotency-Key y el reintento pasa a ser seguro.

curl -sS -X POST https://api.picverce.com/v1/jobs \
  -H "Authorization: Bearer $PICVERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f1c1b8e-2d1a-4f9b-9c3f-0a6d4b2e7c51" \
  -d '{"type":"tool","tool":"enhance",
       "input":{"image_url":"https://example.com/photo.jpg"}}'

La segunda llamada devuelve el trabajo de la primera con Idempotent-Replay: true en las cabeceras y no cobra nada mas. Llega en el estado que haya alcanzado, asi que una repeticion un minuto despues puede venir ya como succeeded.

Dos peticiones son el mismo trabajo cuando coincide la peticion validada: el type, el id de la herramienta o del modelo y la entrada validada. Cambiar el orden de los campos, u omitir un valor que acaba en el mismo predeterminado, no las hace distintas. Enviar un cuerpo realmente distinto con una clave ya usada devuelve 409 idempotency_conflict, porque devolverte un trabajo que no pediste seria peor que pedirte una clave nueva.

Reutilizar una clave mientras la primera peticion sigue en curso da el mismo 409, con un mensaje que lo explica. Espera unos segundos y reintenta.

Webhooks

En lugar de consultar en bucle, registra un endpoint y enviaremos un POST firmado cuando termine un trabajo. Anade uno en Cuenta, API, Webhooks. Hoy existen dos eventos: job.succeeded y job.failed.

POST https://api.tuempresa.com/picverce/webhook
Content-Type: application/json
User-Agent: Picverce-Webhooks/1.0
X-Picverce-Event: job.succeeded
X-Picverce-Delivery: 0f2b1d94-6a3c-4b1e-9d77-2c9e5a1b3d84
X-Picverce-Timestamp: 1756300000
X-Picverce-Signature: v1=8f3c1a...

{
  "id": "evt_11111111222233334444555555555555s",
  "object": "event",
  "type": "job.succeeded",
  "created_at": "2026-08-27T10:00:09.412Z",
  "data": { "object": { ...el mismo trabajo que devuelve GET /v1/jobs/{id}... } }
}

Verifica la firma antes de confiar en el cuerpo. La cadena firmada es la marca de tiempo, un punto y el cuerpo en crudo tal y como llego.

const crypto = require('crypto');

// rawBody tienen que ser los bytes en crudo, no un objeto vuelto a serializar.
function verify(rawBody, headers, secret) {
  const timestamp = headers['x-picverce-timestamp'];
  const received = headers['x-picverce-signature'];
  if (!timestamp || !received) return false;

  // La firma en si nunca caduca, asi que esto es lo que impide un replay.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) return false;

  const expected =
    'v1=' +
    crypto.createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Los endpoints deben ser https y accesibles desde internet. Las direcciones privadas, de loopback y de metadatos de nube se rechazan al registrarlas y de nuevo antes de cada entrega. No seguimos redirecciones, asi que registra la URL final. Un 404 o un 410 desde tu endpoint detiene los reintentos.

Un endpoint que estuvo caido en los tres intentos rapidos no pierde el evento. Se encola y se reintenta unos 30 minutos despues, y luego a las 2, 6 y 12 horas, hasta 10 intentos o 24 horas. Un despliegue que deje tu endpoint caido una hora no te cuesta nada. Pausar un endpoint, o dejar de suscribirte a un evento, tambien detiene sus reintentos en cola.

Claude y MCP

La API REST en api.picverce.com es la plataforma. MCP en mcp.picverce.com es la capa de conector para Claude, Cursor y otros clientes MCP. El servidor MCP alojado llama a los mismos endpoints POST /v1/jobs con tu clave API, consulta trabajos cuando hace falta y devuelve URLs de imagen en los resultados. Creditos, limites de peticiones e idempotencia funcionan igual que en la API directa.

Configura el conector desde la pestana MCP de Cuenta. Crea una clave en la pestana Claves primero.

https://mcp.picverce.com/mcp

En Claude web, abre Ajustes, Conectores, anade un conector personalizado llamado Picverce AI, pega la URL de arriba y usa tu clave API pk_live_ como token Bearer. La clave no aparece en el chat; solo la guarda el conector.

claude mcp add --transport http --scope user picverce-ai https://mcp.picverce.com/mcp

Herramientas MCP (v1)

Estas son las herramientas que ve Claude. Cada una corresponde a trabajos de la API publica o a endpoints del catalogo.

El servidor MCP envia un Idempotency-Key en cada trabajo que crea para que los reintentos de Claude no cobren dos veces. Quien llama la API directa sigue controlando sus propias claves en POST /v1/jobs.

Shopify y otras plataformas

MCP es para asistentes de IA en un chat. Una tienda o un producto SaaS usa la API REST y los webhooks: tu backend guarda la clave de API de Picverce AI del comercio, crea trabajos para las imagenes de producto y escucha job.succeeded para dejar los resultados donde corresponde.

La app de Picverce AI para Shopify esta hecha asi. El comercio la instala, pega su propia clave de API, elige una herramienta y unos productos, y cada imagen terminada se anade al producto como una foto mas. Los originales nunca se reemplazan. Los trabajos gastan los creditos del propio comercio, asi que no hay nada aparte que comprar.

La app esta en tiendas de desarrollo mientras se termina, asi que todavia no hay ficha en la App Store. Si quieres construir lo mismo dentro de tu propio software, todo lo que usa esta en esta pagina: POST /v1/jobs con una Idempotency-Key por imagen, y un webhook firmado cuando cada uno termina.

Consulta la pagina MCP para una guia breve, o la documentacion MCP de Anthropic para detalles del conector.

Referencia completa

La descripcion completa en OpenAPI 3.0 cubre cada endpoint, campo y error. Apunta un generador de clientes hacia ella en vez de escribir los tipos a mano.

Usar la API, el conector MCP o las apps para Shopify y WordPress se rige por los mismos Términos de Servicio y la misma Política de Privacidad que el sitio web, que describen qué envía un trabajo y cuánto tiempo lo guardamos.