Saltar al contenido principal

Desarrolladores

API de Creativox

Crea productos, genera imágenes y recibe webhooks firmados desde tu código, o conecta Claude Code, Codex y Cursor por MCP. Todo se descuenta de los créditos de tu workspace.

Crear una clave API

Primeros pasos

Tres pasos desde cero hasta tu primera imagen generada.

1. Crea una clave API

Inicia sesión, abre Ajustes, pestaña API, y crea una clave (solo propietarios y admins del workspace). Cópiala cuando se muestre: no volverás a verla. Guárdala en una variable de entorno, nunca en el control de versiones.

export CREATIVOX_API_KEY="cvx_live_..."

2. Comprueba que la clave funciona

Lista los modelos disponibles para tu workspace.

curl -H "Authorization: Bearer $CREATIVOX_API_KEY" https://api.creativox.app/api/v1/models

3. Genera tu primera imagen

Envía una generación con una Idempotency-Key para que un reintento nunca te cobre dos veces, y léela hasta que su estado sea completed. Los resultados traen URLs firmadas que caducan; vuelve a pedirlas para obtener nuevas.

curl -X POST https://api.creativox.app/api/v1/generations \
  -H "Authorization: Bearer $CREATIVOX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type": "txt2img", "format": "1:1", "prompt": "A ceramic mug on a travertine table, soft morning light"}'
curl -H "Authorization: Bearer $CREATIVOX_API_KEY" https://api.creativox.app/api/v1/generations/<generation_id>

Autenticación y scopes

Envía la clave como bearer token: Authorization: Bearer cvx_live_... (también se acepta la cabecera X-Api-Key). Cada clave pertenece a un workspace y solo puede hacer lo que sus scopes permiten. Nunca puede gestionar facturación, claves API ni miembros.

Authorization: Bearer cvx_live_...
ScopePermite
generations:readLeer generaciones y sus resultados.
generations:writeCrear generaciones y marcar favoritas.
products:readListar y leer productos.
products:writeCrear, editar y borrar productos; subir imágenes, también desde una URL.
library:readLeer la biblioteca de assets.
account:readLeer la cuenta, el saldo de créditos, los modelos y las plantillas.

Crea claves de solo lectura para paneles y un tope diario de créditos para cada clave que pueda generar.

Errores

Los errores usan estados HTTP estándar y un cuerpo JSON estable. Decide según detail.code, nunca según el texto del mensaje.

Cuerpo de un error
{ "detail": { "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits" } }
EstadoSignificado
400La petición está mal formada.
401Clave ausente, revocada o caducada (API_KEY_INVALID).
402No hay créditos suficientes (INSUFFICIENT_CREDITS).
403La clave no tiene el scope, o el endpoint no está disponible para claves (KEY_NOT_ALLOWED).
404El recurso no existe en tu workspace.
409Conflicto, por ejemplo PLAN_LIMIT_REACHED cuando tu plan no admite otra clave o webhook.
422La validación falló. El detalle indica qué campo.
429Límite de peticiones. Espera la cabecera Retry-After (segundos) antes de reintentar.

Límites por plan

Tu plan fija cuántas claves y endpoints de webhook puedes tener y el tope diario de créditos por defecto de una clave nueva. Las claves existentes siguen funcionando si más adelante se baja un límite.

PlanClaves APITope diario de créditos por defectoEndpoints de webhook
Free1200
Starter52002
Pro20Sin tope5

Los valores vienen directamente de la API.

Webhooks

En vez de consultar cada poco, registra un endpoint HTTPS en Ajustes, pestaña API. Creativox envía un POST firmado cuando una generación termina o falla. Los webhooks siguen la especificación Standard Webhooks.

Eventos: generation.completed y generation.failed. El payload no incluye URLs de imágenes (caducan): llama a GET /api/v1/generations/{id} para obtenerlas.

Payload del evento
{
  "type": "generation.completed",
  "id": "5d6f6b1e-0c5a-4a43-9d3e-2f2b7a1c9e10",
  "created_at": "2026-11-10T12:00:00Z",
  "data": {
    "generation_id": "c1a2b3d4-0000-4000-8000-000000000000",
    "status": "completed",
    "model": "<model-id>",
    "outputs": [{ "id": "<output-id>" }],
    "api_key_id": "<key-id-or-null>"
  }
}

Cada petición lleva las cabeceras webhook-id, webhook-timestamp y webhook-signature (la cadena v1, seguida del HMAC-SHA256 en base64). El contenido firmado es {webhook-id}.{webhook-timestamp}.{cuerpo crudo} y la clave es la parte base64 de tu secreto whsec_.

Responde con cualquier 2xx en menos de 10 segundos. Las entregas fallidas se reintentan a los 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas y 24 horas; tras 20 fallos consecutivos el endpoint se desactiva y se avisa por email al propietario y a los admins. Una entrega puede repetirse: deduplica con webhook-id.

Los destinos deben ser URLs https públicas en el puerto 443 u 8443. Se rechazan redirecciones, credenciales en la URL y direcciones privadas o internas.

Verifica la firma

Verifica el cuerpo crudo de la petición antes de parsearlo. Las librerías oficiales lo hacen por ti; las versiones manuales no necesitan dependencias.

Con la librería oficial

Python
# pip install standardwebhooks
import os
from standardwebhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["CREATIVOX_WEBHOOK_SECRET"])  # whsec_...

def handle(raw_body: bytes, headers: dict):
    try:
        event = wh.verify(raw_body, headers)  # checks signature and timestamp
    except WebhookVerificationError:
        return 400
    # event["type"] is "generation.completed" or "generation.failed"
    return 200
Node.js
// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.CREATIVOX_WEBHOOK_SECRET); // whsec_...

export function handle(rawBody, headers) {
  try {
    const event = wh.verify(rawBody, headers); // checks signature and timestamp
    // event.type is "generation.completed" or "generation.failed"
    return 200;
  } catch {
    return 400;
  }
}

Sin dependencias

Python
import base64, hashlib, hmac, os, time

SECRET = os.environ["CREATIVOX_WEBHOOK_SECRET"]  # whsec_...
KEY = base64.b64decode(SECRET.removeprefix("whsec_"))

def verify(raw_body: bytes, headers: dict) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:  # replay window: 5 minutes
        return False
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(KEY, signed, hashlib.sha256).digest()).decode()
    for part in headers["webhook-signature"].split(" "):
        version, _, sig = part.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False
Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

const KEY = Buffer.from(process.env.CREATIVOX_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

export function verify(rawBody, headers) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
  const expected = createHmac("sha256", KEY).update(`${id}.${ts}.${rawBody}`).digest("base64");
  return headers["webhook-signature"].split(" ").some((part) => {
    const [version, sig] = part.split(",");
    const a = Buffer.from(sig ?? "");
    const b = Buffer.from(expected);
    return version === "v1" && a.length === b.length && timingSafeEqual(a, b);
  });
}

Configurar MCP

El servidor MCP remoto permite que agentes de IA creen productos, suban o importen imágenes, generen imágenes y lean tu biblioteca con la misma clave API y los mismos scopes. Endpoint: https://api.creativox.app/mcp

Claude Code

claude mcp add --transport http creativox https://api.creativox.app/mcp --header "Authorization: Bearer $CREATIVOX_API_KEY"

Codex

Archivo: ~/.codex/config.toml

[mcp_servers.creativox]
url = "https://api.creativox.app/mcp"
bearer_token_env_var = "CREATIVOX_API_KEY"

Cursor

Archivo: .cursor/mcp.json

{
  "mcpServers": {
    "creativox": {
      "url": "https://api.creativox.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CREATIVOX_API_KEY}"
      }
    }
  }
}

El inicio de sesión con OAuth (para los conectores de claude.ai y ChatGPT) llegará próximamente. Por ahora usa una clave API.

Referencia de la API

Generada a partir del documento OpenAPI en vivo. URL base: https://api.creativox.app Documento OpenAPI legible por máquinas

billing

GET/api/v1/billing/balanceRead Billing Balance

Scopes: account:read

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
balanceintegersí
planstringsí
billing_statusBillingStatusno
monthly_quotainteger | nullno
promo_labelstring | nullno

Respuesta 422 Validation Error

generations

GET/api/v1/generationsList Generations

Scopes: generations:read

Parámetros

NombreTipoObligatorioDescripción
limit (query)integerno
offset (query)integerno
status (query)GenerationStatus | nullno
product_id (query)string (uuid) | nullno

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
itemsarray<GenerationRead>sí
items[].idstring (uuid)sí
items[].workspace_idstring (uuid)sí
items[].user_idstring (uuid)sí
items[].product_idstring (uuid) | nullsí
items[].parent_idstring (uuid) | nullsí
items[].promptstringsí
items[].providerstringsí
items[].modelstringsí
items[].typestringsí
items[].statusGenerationStatussí
items[].format1:1 | 9:16 | 16:9 | 4:3 | 3:4 | 4:5sí
items[].image_formatstringsíEncoded image format (e.g. png).
items[].output_urlsarray<string>sí
items[].outputsarray<GenerationOutput>no
items[].outputs[].idstringsí
items[].outputs[].urlstringsí
items[].outputs[].preview_urlstring | nullno
items[].preview_urlstring | nullno
items[].metadataobjectsí
items[].credits_consumedintegersí
items[].is_favoritebooleansí
items[].created_atstring (date-time)sí
items[].updated_atstring (date-time)sí
totalintegersí

Respuesta 422 Validation Error

POST/api/v1/generationsCreate Generation

Scopes: generations:write

Cuerpo de la petición

NombreTipoObligatorioDescripción
template_idstring (uuid) | nullno
template_slugstring | nullno
template_varsobjectno
promptstring | nullno
format1:1 | 9:16 | 16:9 | 4:3 | 3:4 | 4:5síOutput aspect ratio.
product_idstring (uuid) | nullno
parent_idstring (uuid) | nullno
typetxt2img | img2imgsítxt2img or img2img.
modelstring | nullnoModel ID. If omitted, uses the default model.
num_imagesintegernoImages to generate in this request (default 1). Must not exceed the model's `max_images` (GET /models); credits charged = per-image cost x num_images.
model_promptstring | nullnoPrompt traducido a inglés en el cliente para enviar al proveedor; el prompt visible sigue siendo `prompt`.

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
workspace_idstring (uuid)sí
user_idstring (uuid)sí
product_idstring (uuid) | nullsí
parent_idstring (uuid) | nullsí
promptstringsí
providerstringsí
modelstringsí
typestringsí
statusGenerationStatussí
format1:1 | 9:16 | 16:9 | 4:3 | 3:4 | 4:5sí
image_formatstringsíEncoded image format (e.g. png).
output_urlsarray<string>sí
outputsarray<GenerationOutput>no
outputs[].idstringsí
outputs[].urlstringsí
outputs[].preview_urlstring | nullno
preview_urlstring | nullno
metadataobjectsí
credits_consumedintegersí
is_favoritebooleansí
created_atstring (date-time)sí
updated_atstring (date-time)sí

Respuesta 422 Validation Error

GET/api/v1/generations/{generation_id}Get Generation

Scopes: generations:read

Parámetros

NombreTipoObligatorioDescripción
generation_id (path)string (uuid)sí

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
workspace_idstring (uuid)sí
user_idstring (uuid)sí
product_idstring (uuid) | nullsí
parent_idstring (uuid) | nullsí
promptstringsí
providerstringsí
modelstringsí
typestringsí
statusGenerationStatussí
format1:1 | 9:16 | 16:9 | 4:3 | 3:4 | 4:5sí
image_formatstringsíEncoded image format (e.g. png).
output_urlsarray<string>sí
outputsarray<GenerationOutput>no
outputs[].idstringsí
outputs[].urlstringsí
outputs[].preview_urlstring | nullno
preview_urlstring | nullno
metadataobjectsí
credits_consumedintegersí
is_favoritebooleansí
created_atstring (date-time)sí
updated_atstring (date-time)sí

Respuesta 422 Validation Error

PATCH/api/v1/generations/{generation_id}/favoriteToggle Generation Favorite

Scopes: generations:write

Parámetros

NombreTipoObligatorioDescripción
generation_id (path)string (uuid)sí

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
is_favoritebooleansí

Respuesta 422 Validation Error

library

GET/api/v1/libraryList Library

Scopes: library:read

Parámetros

NombreTipoObligatorioDescripción
limit (query)integernoPage size (max 100).
cursor (query)string | nullnoOpaque cursor from the previous page's `next_cursor` (base64url JSON: `created_at` ISO-8601 + `id` UUID).
status (query)GenerationStatus | nullno
is_favorite (query)boolean | nullnoWhen set, only favorites (true) or non-favorites (false).
product_id (query)string (uuid) | nullno

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
itemsarray<GenerationRead>sí
items[].idstring (uuid)sí
items[].workspace_idstring (uuid)sí
items[].user_idstring (uuid)sí
items[].product_idstring (uuid) | nullsí
items[].parent_idstring (uuid) | nullsí
items[].promptstringsí
items[].providerstringsí
items[].modelstringsí
items[].typestringsí
items[].statusGenerationStatussí
items[].format1:1 | 9:16 | 16:9 | 4:3 | 3:4 | 4:5sí
items[].image_formatstringsíEncoded image format (e.g. png).
items[].output_urlsarray<string>sí
items[].outputsarray<GenerationOutput>no
items[].outputs[].idstringsí
items[].outputs[].urlstringsí
items[].outputs[].preview_urlstring | nullno
items[].preview_urlstring | nullno
items[].metadataobjectsí
items[].credits_consumedintegersí
items[].is_favoritebooleansí
items[].created_atstring (date-time)sí
items[].updated_atstring (date-time)sí
next_cursorstring | nullnoOpaque cursor for the next page: base64url-encoded JSON `{"created_at":"<ISO-8601>","id":"<uuid>"}` matching the last item on this page. Omit on the first request; pass the previous `next_cursor` to continue.
has_morebooleansíTrue when more items exist after `items` using `next_cursor`.

Respuesta 422 Validation Error

mcp

POST/mcpRemote MCP (Streamable HTTP)

Stateless JSON-RPC MCP tools with workspace bearer API keys. Requests with a progress token receive SSE. Tool scopes match REST. See https://github.com/modelcontextprotocol/python-sdk for MCP clients.

Scopes: Cualquier clave válida

Respuesta 200 MCP JSON-RPC result or SSE stream

me

GET/api/v1/meRead Me

Scopes: account:read

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
workspaceKeyWorkspaceOutsí
workspace.idstring (uuid)sí
workspace.namestringsí
keyCurrentKeyOutsí
key.idstring (uuid)sí
key.namestringsí
key.prefixstringsí
key.scopesarray<string>sí

Respuesta 422 Validation Error

models

GET/api/v1/modelsList Available Models

Scopes: account:read

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
[].model_idstringsí
[].providerstringsí
[].display_namestringsí
[].descriptionstringsí
[].credit_costintegersí
[].speed_tierstringsí
[].quality_tierstringsí
[].capabilitiesarray<string>sí
[].supported_aspectsarray<string>sí
[].max_resolutionstringsí
[].is_defaultbooleansí
[].max_imagesintegersíLargest `num_images` POST /generations accepts for this model.

Respuesta 422 Validation Error

products

GET/api/v1/productsList Products

Scopes: products:read

Parámetros

NombreTipoObligatorioDescripción
limit (query)integerno
offset (query)integerno

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
itemsarray<ProductRead>sí
items[].idstring (uuid)sí
items[].workspace_idstring (uuid)sí
items[].namestringsí
items[].descriptionstring | nullsí
items[].product_typeropa | joyeria | belleza | hogar | suplementos | nullsí
items[].base_imagesarray<string>sí
items[].image_urlsobjectno
items[].created_atstring (date-time)sí
items[].updated_atstring (date-time)sí
totalintegersí

Respuesta 422 Validation Error

POST/api/v1/productsCreate Product

Scopes: products:write

Cuerpo de la petición

NombreTipoObligatorioDescripción
namestringsí
descriptionstring | nullno
product_typeropa | joyeria | belleza | hogar | suplementos | nullno

Respuesta 201 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
workspace_idstring (uuid)sí
namestringsí
descriptionstring | nullsí
product_typeropa | joyeria | belleza | hogar | suplementos | nullsí
base_imagesarray<string>sí
image_urlsobjectno
created_atstring (date-time)sí
updated_atstring (date-time)sí

Respuesta 422 Validation Error

GET/api/v1/products/{product_id}Get Product

Scopes: products:read

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
workspace_idstring (uuid)sí
namestringsí
descriptionstring | nullsí
product_typeropa | joyeria | belleza | hogar | suplementos | nullsí
base_imagesarray<string>sí
image_urlsobjectno
created_atstring (date-time)sí
updated_atstring (date-time)sí

Respuesta 422 Validation Error

PATCH/api/v1/products/{product_id}Update Product

Scopes: products:write

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí

Cuerpo de la petición

NombreTipoObligatorioDescripción
namestring | nullno
descriptionstring | nullno
product_typeropa | joyeria | belleza | hogar | suplementos | nullno

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
workspace_idstring (uuid)sí
namestringsí
descriptionstring | nullsí
product_typeropa | joyeria | belleza | hogar | suplementos | nullsí
base_imagesarray<string>sí
image_urlsobjectno
created_atstring (date-time)sí
updated_atstring (date-time)sí

Respuesta 422 Validation Error

DELETE/api/v1/products/{product_id}Delete Product

Scopes: products:write

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí

Respuesta 204 Successful Response

Respuesta 422 Validation Error

POST/api/v1/products/{product_id}/confirm-uploadConfirm Upload

Scopes: products:write

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí

Cuerpo de la petición

NombreTipoObligatorioDescripción
keystringsí

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
idstring (uuid)sí
workspace_idstring (uuid)sí
namestringsí
descriptionstring | nullsí
product_typeropa | joyeria | belleza | hogar | suplementos | nullsí
base_imagesarray<string>sí
image_urlsobjectno
created_atstring (date-time)sí
updated_atstring (date-time)sí

Respuesta 422 Validation Error

POST/api/v1/products/{product_id}/images/from-urlImport Product Image

Scopes: products:write

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí

Cuerpo de la petición

NombreTipoObligatorioDescripción
urlstringsí

Respuesta 202 Successful Response

Respuesta 422 Validation Error

GET/api/v1/products/{product_id}/images/imports/{import_id}Get Product Image Import

Scopes: products:read

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí
import_id (path)string (uuid)sí

Respuesta 200 Successful Response

Respuesta 422 Validation Error

POST/api/v1/products/{product_id}/upload-urlRequest Upload Url

Scopes: products:write

Parámetros

NombreTipoObligatorioDescripción
product_id (path)string (uuid)sí

Cuerpo de la petición

NombreTipoObligatorioDescripción
filenamestringsí
content_typestringsí
content_lengthintegersíExact byte size of the file to upload. It is validated against the product image size policy and bound into the presigned URL signature, so storage rejects any body of a different size.

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
urlstringsí
methodstringno
headersobjectsí
upload_idstringsí
curlstringsí
upload_urlstringsí
keystringsí
expires_inintegersí

Respuesta 422 Validation Error

templates

GET/api/v1/templatesList Templates

List active global templates (not scoped to workspace).

Scopes: account:read

Respuesta 200 Successful Response

NombreTipoObligatorioDescripción
itemsarray<TemplateRead>sí
items[].idstring (uuid)sí
items[].namestringsí
items[].slugstring | nullsí
items[].categorystringsí
items[].descriptionstring | nullsí
items[].prompt_templatestringsí
items[].preview_urlstring | nullsí
items[].default_formatstringsí
items[].product_typesarray<string>sí
items[].formatsarray<string>sí
items[].is_activebooleansí
items[].sort_orderintegersí
items[].created_atstring (date-time)sí
items[].updated_atstring (date-time)sí