# API de SciFig y servidor MCP

Crea figuras científicas, gráficos y diagramas de flujo desde código o asistentes de IA. Versión legible: https://scifig.ai/es/developers. OpenAPI: https://scifig.ai/api/v1/openapi.json.

## Resumen

La API de SciFig crea figuras científicas, gráficos y diagramas de flujo con los mismos motores, precios y créditos que el sitio web. La URL base es `https://scifig.ai/api/v1`. Cada creación es un trabajo: lo creas y después consultas su estado y sus archivos de salida.

Los asistentes de IA pueden usar SciFig a través del servidor MCP remoto en `https://mcp.scifig.ai/mcp` (consulta «Servidor MCP» más abajo).

## Autenticación

Envía `Authorization: Bearer <credential>` en cada solicitud, excepto a `/pricing`, `/openapi.json` y `/openapi.yaml`.

- Las claves con algún permiso de escritura requieren una suscripción activa o saldo positivo de un paquete y caducan a los 30, 90 o 365 días. Las claves de solo lectura pueden no caducar.
- Tokens de acceso OAuth (`sf_at_…`): se entregan a los clientes MCP tras tu aprobación y duran una hora. Los clientes que solicitan `offline_access` reciben también un token de actualización (`sf_rt_…`) válido durante 30 días. Revoca una aplicación en Configuración → Claves API → Aplicaciones conectadas.
- Las ocho autorizaciones se eligen por separado. Ninguna incluye otra; subir archivos, consultar tareas y consultar el saldo requieren sus propios permisos. `images:generate`, `images:edit`, `images:convert`, `charts:generate`, `flowcharts:generate`, `files:write`, `jobs:read`, `credits:read`
- `GET /api/v1/capabilities` requiere credenciales válidas, sin permisos de negocio. Solo devuelve `granted_scopes`, sin saldo, plan ni datos de la cuenta.
- Todas las llamadas autenticadas, incluidos los errores de permisos y otros fallos, conservan metadatos durante 30 días. No se guardan prompts, contenido, nombres de archivo, IP ni credenciales. Puede haber pérdidas durante fallos de la plataforma. Claves, historial y aplicaciones conectadas muestran 10 filas por página por separado. Los créditos son la liquidación de la tarea asociada; no sumes las filas de reintentos como gasto adicional.
- Solo los clientes `CIMD` permitidos pueden usar `private_key_jwt` con firma de clave pública verificada y protección contra repetición. El registro dinámico anónimo sigue limitado a `none` o `client_secret_basic`.

## Inicio rápido

```bash
curl https://scifig.ai/api/v1/images/generations \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Mitochondrial electron transport chain, labelled", "aspect_ratio": "4:3"}'
```

La respuesta contiene el trabajo. Si aún no ha terminado, el estado es `202` con `Location: /api/v1/jobs/{id}`. Consulta esa URL cada pocos segundos hasta que `status` sea `succeeded`, `failed` o `canceled` y descarga los resultados desde `outputs[].download_url`.

## Convenciones

- Las solicitudes y las respuestas usan JSON; las cargas de archivos y los datos de gráficos usan `multipart/form-data`. Los nombres de los campos siguen `snake_case`.
- Cada `POST` que crea un resultado requiere una cabecera `Idempotency-Key` (1–255 caracteres ASCII visibles). Reintentar con la misma clave y el mismo cuerpo devuelve el mismo trabajo y nunca cobra dos veces; usar la misma clave con otro cuerpo devuelve `409 IDEMPOTENCY_CONFLICT`. Dos solicitudes simultáneas con la misma clave devuelven el mismo trabajo, o `409 IDEMPOTENCY_IN_PROGRESS` mientras la otra aún se está admitiendo. Una solicitud rechazada (por ejemplo, `INSUFFICIENT_CREDITS`) conserva esa respuesta para su clave: tras recargar o mejorar la suscripción, envíala con una nueva clave. Una vez creado el trabajo, un error reintentable (`429`, `503`, `409 IDEMPOTENCY_IN_PROGRESS`) o `500 INTERNAL_ERROR` incluye `details.job_id`: reintenta con la misma clave o consulta `GET /jobs/{job_id}`, sin usar una clave nueva. Un trabajo aceptado que no pudo leerse devuelve `202` y el estado `queued`.
- `Prefer: wait=N` (1–30 segundos) mantiene la respuesta en espera hasta que el trabajo termine o se agote el tiempo.
- Cada respuesta incluye `X-Request-Id`. Los errores usan `{"error": {"code", "message", "request_id", "details"}}`.
- La API no está disponible para navegadores mediante CORS; llámala desde un servidor o un script.

## Endpoints y créditos

| Endpoint | Uso | Créditos |
| --- | --- | --- |
| POST /images/generations | Generar una ilustración científica | 50 / 75 / 100 (standard / advanced / premium) |
| POST /images/edits | Editar una imagen: mediante instrucciones, una máscara para redibujar una región, fondo blanco, relación de aspecto, cambio de colores o sustitución de texto | 50 / 75 / 100; con máscara o `replace_text` 100 |
| POST /images/text-detections | Detectar el texto de una imagen antes de sustituirlo | 0 |
| POST /images/upscales | Ampliar a 2K, 4K u 8K | 50 / 100 / 150 |
| POST /images/conversions | Convertir a SVG, PNG, PDF, TIFF o PPTX; los SVG de diagramas de flujo a PNG, PDF, TIFF o PPTX | SVG 150; otros formatos gratis, 200 al día |
| POST /charts/generations | Crear un gráfico con datos CSV, TSV o Excel | 100 |
| POST /charts/edits | Modificar la versión más reciente de un gráfico | 100 |
| POST /flowcharts/generations | Dibujar un diagrama de flujo en SVG | 100 |
| POST /flowcharts/edits | Modificar la versión más reciente de un diagrama de flujo | 100 |
| POST /files | Subir una imagen, una máscara o un archivo adjunto para un diagrama de flujo | 0 |
| GET /jobs/{id} | Estado, créditos y enlaces de descarga de una tarea | 0 |
| GET /jobs | Tus tareas recientes, de la más nueva a la más antigua, con paginación por cursor | 0 |
| GET /files/{file_id} | Descargar un archivo | 0 |
| GET /credits | Saldo, plan y límites de tareas | 0 |
| GET /pricing | Precio en créditos de cada operación, sin autenticación | 0 |
| GET /openapi.json | Descripción OpenAPI 3.1, sin autenticación | 0 |
| GET /openapi.yaml | La misma descripción en YAML | 0 |

## Campos de la solicitud

`POST /images/generations`: `prompt` (obligatorio), `aspect_ratio` (`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`), `quality` (`standard`, `advanced`, `premium`), `style`, `palette` (identificador de un ajuste predefinido o 1–4 colores `#RRGGBB`), `reference_file_ids` (hasta 3). Algunos modelos e imágenes de referencia requieren un plan de pago; el error lo indica.

`POST /images/edits`: `image` (una `file_id`) y `operation`. `instruct` (por defecto) acepta `instruction` (hasta 2000 caracteres) y una `mask` opcional (PNG; el blanco marca el área modificable; una máscara siempre usa el modelo `premium`). `white_background` sustituye el fondo por blanco sólido. `aspect_ratio` ajusta la imagen a `aspect_ratio`. `recolor` aplica `palette` (1–8 colores `#RRGGBB`) o elige una paleta. Todas estas operaciones aceptan `quality`. `replace_text` acepta `text_detection` (el identificador de `POST /images/text-detections` para la misma imagen) y `replacements` (`[{"index", "text"}]`), y siempre usa el modelo `premium` de edición de texto.

`POST /images/text-detections`: `image`. Devuelve `id`, las dimensiones `width` y `height` de la imagen y `texts` (`index`, `text`, `corners`) en orden de lectura. Gratis; comparte con el sitio el límite de 20 detecciones cada 15 minutos.

`POST /images/upscales`: `image`, `scale` (`2k`; `4k` necesita al menos Starter y `8k` al menos Plus; un saldo de paquete de créditos superior a cero cuenta como Pro).

`POST /images/conversions`: `image`, `format` (`svg`, `png`, `pdf`, `tiff`, `pptx`). Para SVG, `vector_mode` es `editable_text` (por defecto) o `full_vector`; la fuente es una imagen PNG, JPEG o WebP. Para otros formatos, `dpi` es 300, 600 o 1000. Los DPI se escriben como metadatos y definen el tamaño de la página; no se remuestrean los píxeles (amplía primero para obtener más píxeles). La fuente es una imagen PNG o JPEG o el SVG de un diagrama de flujo; no se admite WebP y PNG y TIFF necesitan una fuente PNG. El SVG de un diagrama de flujo se renderiza en el servidor con Arial y Noto. `width` (256–4096, por defecto 2048) fija el lado largo en píxeles; se rechaza el texto que esas fuentes no pueden representar. El PPTX contiene la imagen renderizada, no formas editables.

`POST /charts/generations` (`multipart`): `data` (CSV, TSV, TXT, XLSX o XLS, hasta 8 MB; se detecta el delimitador de los archivos de texto), `request` (qué dibujar, 1–16.000 caracteres), y los campos opcionales `chart_types` (separados por comas), `journal_style` (`default`, `nature`, `science`, `cell`, `plos`, `acs`), `figure_width` (`single`, `onehalf`, `double`), `color_palette`, `sheet_name` (hoja de un libro con varias hojas). Los datos ilegibles devuelven `400 INVALID_REQUEST`, con `details.field = data` y el código del analizador en `details.reason`. Salidas: PNG, PDF, TIFF y EPS.

`POST /charts/edits` y `POST /flowcharts/edits`: `job` (trabajo anterior de gráfico o diagrama de flujo) e `instruction` (1–16.000 caracteres para gráficos, 1–8000 para diagramas de flujo). La edición continúa desde el resultado de ese trabajo y conserva los datos, tipos de gráfico y estilo de revista (gráficos) o la relación de aspecto (diagramas de flujo). Como en el espacio de trabajo, solo puedes editar la versión más reciente. Si existe una nueva versión (también creada en el sitio), la respuesta es `409 REVISION_CONFLICT` con `details.reason = NOT_LATEST_REVISION`. Mientras el trabajo padre sigue en curso, devuelve un error reintentable `409 REVISION_CONFLICT` (`PARENT_JOB_RUNNING`, con `Retry-After`); si el padre falló, devuelve `400 INVALID_REQUEST` (`JOB_NOT_SUCCEEDED`).

`POST /flowcharts/generations`: `prompt` (1–8000 caracteres), `aspect_ratio` (`auto` o una de las relaciones anteriores), y `attachment_file_ids` opcional (hasta 8, cargados con el uso `flowchart_attachment`). Salida: SVG.

## Trabajos

`status` es `queued`, `processing`, `succeeded`, `failed` o `canceled`. `credits` muestra `reserved`, `charged` y `refunded`, leídos del registro contable. Un trabajo fallido devuelve sus créditos.

Una generación o edición que agota el tiempo tiene estado `failed`, `error.code = TASK_TIMED_OUT` y la marca temporal `late_delivery_until`. Hasta entonces, el resultado aún puede entregarse gratis; sigue consultando el trabajo en lugar de crear otro.

Un rechazo de la política de contenido devuelve `422 CONTENT_REJECTED` al crear la solicitud, o un trabajo `failed` con `error.code = CONTENT_REJECTED` si ocurre durante su ejecución. Ambos casos devuelven los créditos.

Cada salida tiene una `file_id`, un `format` y una `download_url` válida una hora sin credenciales. Las salidas PNG también incluyen `width` y `height`. Los gráficos y diagramas de flujo contienen una `editor_url` que abre el resultado en su espacio de trabajo del sitio; las ilustraciones y conversiones no la tienen.

Las imágenes de salida (PNG, JPEG, WebP) pueden pasarse por `file_id` como `image` o referencia a los endpoints de imagen. Las conversiones aceptan fuentes de hasta 20 MB. Para PNG, PDF, TIFF y PPTX aceptan imágenes PNG o JPEG y el SVG de un diagrama de flujo, pero no WebP.

## Archivos

`POST /files` (`multipart`): `file` y `purpose` (`image`, `mask` o `flowchart_attachment`). Imágenes: PNG, JPEG o WebP de hasta 20 MB; máscaras: PNG de hasta 8 MB; adjuntos de diagramas de flujo: formatos del espacio de trabajo FlowChart, hasta 32 MB. La respuesta es `201` con `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at` y `created_at`. Los archivos cargados se pueden usar durante 24 horas. Comparten los límites de carga del sitio; al superarlos, la respuesta es `429 RATE_LIMITED`. Una `Idempotency-Key` opcional (1–255 caracteres ASCII visibles) permite repetir la carga: la misma cuenta, clave y `purpose` devuelven el primer archivo con `201`, sin volver a cargarlo ni consumir el límite. La misma clave y `purpose` con otros bytes devuelven `409 IDEMPOTENCY_CONFLICT`. Repetir una carga caducada devuelve `400 INVALID_REQUEST` con `details.reason = FILE_EXPIRED`; vuelve a cargar el archivo con una nueva clave.

`GET /files/{file_id}` descarga tu archivo con tus credenciales o con la `download_url` firmada de un trabajo. Un enlace firmado caducado o alterado devuelve `404`, igual que todos los enlaces de una cuenta bloqueada o en proceso de eliminación.

## Errores

| Código | HTTP | Significado |
| --- | --- | --- |
| UNAUTHORIZED | 401 | Faltan credenciales o no son válidas. |
| ACCOUNT_UNAVAILABLE | 401 | Esta cuenta no puede usar la API. |
| SCOPE_DENIED | 403 | Las credenciales no conceden este permiso. |
| INVALID_REQUEST | 400 | La solicitud no es válida. |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Se requiere una cabecera Idempotency-Key de 1 a 255 caracteres ASCII visibles. |
| IDEMPOTENCY_CONFLICT | 409 | Este Idempotency-Key ya se ha usado con una solicitud diferente. |
| IDEMPOTENCY_IN_PROGRESS | 409 | Todavía se está procesando una solicitud con este Idempotency-Key. |
| NOT_FOUND | 404 | No se ha encontrado. |
| REVISION_CONFLICT | 409 | La tarea del gráfico o diagrama de flujo no se puede editar ahora: `NOT_LATEST_REVISION`, `EDIT_IN_PROGRESS` o `PARENT_JOB_RUNNING` mientras la tarea principal siga en ejecución. |
| PAYLOAD_TOO_LARGE | 413 | El cuerpo de la solicitud es demasiado grande. |
| INSUFFICIENT_CREDITS | 402 | No hay suficientes créditos. |
| CONTENT_REJECTED | 422 | La política de contenido ha rechazado la solicitud. Se devuelve como `422` al crear la solicitud o como `error.code` de una tarea fallida si ocurre durante la ejecución; los créditos se devuelven en ambos casos. |
| PLAN_REQUIRED | 403 | Tu plan no incluye esta opción. |
| RATE_LIMITED | 429 | Demasiadas solicitudes, tareas por hora, conversiones por día o subidas; `details.reason` indica la causa. |
| CONCURRENCY_LIMITED | 429 | Hay demasiadas tareas en ejecución para esta cuenta. |
| SERVICE_UNAVAILABLE | 503 | El servicio no está disponible temporalmente. Vuelve a intentarlo con el mismo Idempotency-Key. |
| TASK_FAILED | 502 | La tarea ha fallado y se han devuelto sus créditos. Envía una nueva solicitud con un nuevo Idempotency-Key para volver a intentarlo. |
| INTERNAL_ERROR | 500 | Error interno. |

`details.reason` indica la causa exacta de `INVALID_REQUEST`, `PLAN_REQUIRED` y errores similares. Solo `INSUFFICIENT_CREDITS` incluye `details.top_up_url`; su `utm_source` es `api` o `mcp` según el canal de la solicitud.

Códigos que aparecen solo dentro de un trabajo fallido:

| error.code | Significado | Qué hacer |
| --- | --- | --- |
| TASK_TIMED_OUT | La tarea ha superado el tiempo límite y se han devuelto los créditos. La generación o edición de una ilustración puede incluir `late_delivery_until`: hasta ese momento el resultado puede llegar gratis. | Sigue consultando la tarea hasta `late_delivery_until`; en otro caso, envía una solicitud nueva con una clave nueva |
| CONTENT_REJECTED | La política de contenido ha rechazado el resultado durante la ejecución; se han devuelto los créditos. El mismo código se devuelve como `422` cuando se rechaza la propia solicitud al crearla. | Cambia la descripción o la entrada y usa una clave nueva |
| ADMISSION_INCOMPLETE | La tarea nunca se inició porque un error que permite reintentar lo impidió. No se consumieron créditos. | Envía la misma solicitud con el mismo Idempotency-Key |
| TASK_NOT_FOUND | La tarea se admitió, pero ya no se encuentra su ejecución. | Envía una solicitud nueva con una clave nueva |
| TASK_FAILED | La tarea ha fallado y se han devuelto los créditos. Cualquier error del motor sin código público propio pasa a ser `TASK_FAILED`; el código del motor está en `details.reason`. | Envía una solicitud nueva con una clave nueva |
| INTERNAL_ERROR | La tarea ha fallado sin indicar el motivo; se han devuelto los créditos. | Envía una solicitud nueva con una clave nueva |

## Límites de solicitudes

- Creación: 20 solicitudes por minuto y credencial, y 40 por minuto y cuenta. Una credencial OAuth se contabiliza por cliente y cuenta.
- Lectura: 120 solicitudes por minuto y credencial.
- Los trabajos simultáneos dependen de tu plan; se inician como máximo 200 por hora. Ambos límites se comparten con el sitio.
- Las respuestas que superan la autenticación y la comprobación de permisos incluyen `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`; una respuesta `429` incluye `Retry-After`.
- `429 RATE_LIMITED` tiene varias causas; consulta `details.reason` y la [página de límites de solicitudes](/es/docs/api/rate-limits).

## Instala el plugin oficial de SciFig

Añade el marketplace de SciFig en Claude Code para instalar la conexión MCP remota y cuatro skills para la configuración, las figuras, los gráficos y la exportación.

```text
/plugin marketplace add lilingm963/scifig-plugins
/plugin install scifig@scifig-plugins
```

- [Introducción a la API y MCP](/es/developers)
- [Guía de instalación de MCP](/es/developers/mcp/install.md)
- [Referencia de la API](/es/docs/api)
- [Explorar el plugin oficial](https://github.com/lilingm963/scifig-plugins)
- [Ficha en MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.lilingm963%2Fscifig/versions/1.0.0)

## Servidor MCP

URL del servidor: `https://mcp.scifig.ai/mcp`, Streamable HTTP. Los clientes compatibles con OAuth se conectan iniciando sesión en SciFig y autorizando el acceso; los que envían cabeceras pueden usar una clave API como `Authorization: Bearer sk_live_…`.

| Herramienta | Función |
| --- | --- |
| generate_figure | Crear una ilustración científica a partir de una descripción |
| edit_figure | Editar una imagen: instrucciones, opcionalmente una región enmascarada, fondo blanco, relación de aspecto, cambio de colores o sustitución de texto |
| detect_text | Detectar el texto de una imagen antes de sustituirlo |
| upscale_figure | Ampliar a 2K, 4K u 8K |
| convert_figure | Convertir a SVG, PNG, PDF, TIFF o PPTX |
| generate_chart | Crear un gráfico a partir de texto CSV o TSV o filas JSON, hasta 1 MB |
| edit_chart | Modificar la versión más reciente de un gráfico |
| generate_flowchart | Dibujar un diagrama de flujo en SVG, opcionalmente a partir de hasta 8 archivos adjuntos |
| edit_flowchart | Modificar la versión más reciente de un diagrama de flujo |
| get_job | Estado, créditos y enlaces de descarga de una tarea |
| list_figures | Tareas recientes |
| get_credit_balance | Saldo de créditos, plan y límites |

Las herramientas de creación esperan hasta 25 segundos. Si una tarea sigue ejecutándose, llama a `get_job` más tarde; volver a llamar a la herramienta de creación crea y cobra una tarea nueva. Los resultados incluyen cada enlace de descarga y, para gráficos y diagramas de flujo, el enlace que abre el resultado en el editor de SciFig.

La inicialización usa `/capabilities` sin necesitar `credits:read`. Cada herramienta exige su permiso. Subir desde una URL externa o data URL requiere además `files:write`, comprobado antes de descargar; reutilizar un `file_id` no lo requiere. Las descargas integradas y `get_job` necesitan `jobs:read`. Si falta, conserva el resultado y explica la limitación sin ampliar permisos sin consentimiento.

## Conecta tu cliente

Claude, en claude.ai y Claude Desktop: Ajustes → Conectores → Añadir conector personalizado. Introduce la URL del servidor, inicia sesión en SciFig y permite el acceso.

Abre `Plugins` en ChatGPT y añade una conexión MCP personalizada privada. Los menús dependen de la cuenta.

Claude Code:

```bash
claude mcp add --transport http scifig https://mcp.scifig.ai/mcp
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.scifig]
url = "https://mcp.scifig.ai/mcp"
```

Abre Cursor `Customize` → MCP y edita `mcp.json` conservando los servidores existentes. Después, selecciona `Authenticate` y autoriza SciFig en el navegador.

```json
{
  "mcpServers": {
    "scifig": {
      "url": "https://mcp.scifig.ai/mcp"
    }
  }
}
```

Los clientes sin OAuth pueden añadir la cabecera `Authorization: Bearer sk_live_…` con una clave API creada en Configuración → Claves API.