Referencia de la API

Creación y edición de gráficos

Crea gráficos listos para publicar a partir de tus datos y después modifícalos con instrucciones adicionales.

Campos del formulario#

POST /charts/generations acepta multipart/form-data. Ámbito requerido: figures:generate.

Campo	Tipo	Obligatorio	Valor predeterminado	Reglas
data	file	sí	—	CSV, TSV, TXT, XLSX o XLS de hasta 8 MB, con fila de cabecera; se detecta el delimitador de CSV, TSV y TXT: coma, tabulación o punto y coma
request	string	sí	—	Qué representar, en lenguaje natural; 1–16.000 caracteres
chart_types	string	no	elegido a partir de los datos	Separados por comas o como matriz JSON; consulta la lista más abajo
journal_style	string	no	`default`	`default`, `nature`, `science`, `cell`, `plos` o `acs`
figure_width	string	no	`double`	Ancho de columna `single`, `onehalf` o `double`; PLOS y ACS no tienen `onehalf`
color_palette	string	no	`okabe_ito`	`okabe_ito`, `wong`, `tol_bright`, `tol_muted`, `nature`, `science`, `nejm`, `lancet` o `jama`
sheet_name	string	para libros con varias hojas	—	La hoja de un archivo XLSX o XLS que se usará para el gráfico; 1–255 caracteres

Errores de datos#

Los datos se analizan antes de crear nada, con el mismo analizador que el sitio web. Los datos ilegibles devuelven 400 INVALID_REQUEST con details.field = data y el código del analizador en details.reason, por ejemplo DATACHART_CSV_INVALID o DATACHART_TOO_MANY_ROWS. No se ejecuta ninguna tarea ni se consumen créditos.
Un libro con varias hojas sin sheet_name devuelve 400 INVALID_REQUEST con DATACHART_WORKSHEET_REQUIRED y los nombres de las hojas en details.sheet_names; envía de nuevo la solicitud con sheet_name. Un sheet_name desconocido devuelve DATACHART_WORKSHEET_INVALID, también con details.sheet_names.
Un tipo de archivo fuera de la lista devuelve UNSUPPORTED_DATA_FORMAT; un archivo que supera el tamaño límite devuelve DATA_FILE_TOO_LARGE.
Cada archivo de datos nuevo cuenta para los límites de subida del sitio web; al superarlos, la respuesta es 429 RATE_LIMITED con UPLOAD_RATE_LIMITED o UPLOAD_DAILY_LIMIT_REACHED. Reintentar con la misma clave no vuelve a contar el archivo.

Tipos de gráficos#

bar, line, scatter, dot, frequency_dot, pie, nested_pie, timeseries, waterfall, stacked_area, radar, boxplot, violin, histogram, density, raincloud, beeswarm, qq, ogive, ecdf, ridgeline, regression, errorbar, correlation, bland_altman, funnel, standard_curve, bubble, hexbin, paired_dot, volcano, kaplan_meier, forest, roc, manhattan, ma_plot, enrichment, dose_response, growth_curve, enzyme_kinetics, precision_recall, calibration_curve, confusion_matrix, heatmap, dendrogram, upset, sankey, stem_leaf, calendar_heatmap

Resultados y créditos#

100 créditos por gráfico. Una tarea completada genera la misma figura en PNG, PDF, TIFF y EPS, dimensionada para la columna de la revista. Cada resultado incluye editor_url, que abre el gráfico en su conversación DataChart en el sitio web.

Ediciones#

POST /charts/edits con JSON {"job": "<chart job id>", "instruction": "..."} modifica el gráfico generado por esa tarea y conserva sus datos, tipos de gráficos, estilo de revista y paleta. instruction tiene 1–16.000 caracteres. 100 créditos, como en el espacio de trabajo.

La tarea debe ser una de tus tareas de gráficos; en otro caso, 400 INVALID_REQUEST con JOB_NOT_FOUND. Si ha fallado, la respuesta es 400 INVALID_REQUEST con JOB_NOT_SUCCEEDED.
Si sigue ejecutándose, la respuesta es 409 REVISION_CONFLICT con details.reason = PARENT_JOB_RUNNING y Retry-After. Este error permite reintentar: envía la misma solicitud con la misma clave cuando la tarea haya terminado.
Solo se puede editar la versión más reciente, como en el espacio de trabajo. Edita la tarea más nueva de la cadena; una anterior devuelve 409 REVISION_CONFLICT con NOT_LATEST_REVISION, también si se creó una versión posterior en el sitio web o se aceptó primero otra edición de la misma versión.
Una edición a la vez: mientras se ejecuta una edición de la versión actual, otra devuelve 409 REVISION_CONFLICT con EDIT_IN_PROGRESS. Espera a la tarea en curso y edita después su resultado.
Un gráfico creado en el sitio web antes del formato de gráficos actual no se puede continuar mediante la API: 400 INVALID_REQUEST con JOB_NOT_EDITABLE.
Las ediciones realizadas mediante la API aparecen en la misma conversación DataChart del sitio web.

cURL#

curl -X POST https://scifig.ai/api/v1/charts/generations \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -F "data=@measurements.csv" \
  -F "request=Box plot of response by group with individual points" \
  -F "journal_style=nature"

JavaScript#

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('data', new Blob([await readFile('measurements.csv')]), 'measurements.csv');
form.set('request', 'Box plot of response by group with individual points');
form.set('journal_style', 'nature');

const response = await fetch('https://scifig.ai/api/v1/charts/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    Prefer: 'wait=25',
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);

Python#

import os
import uuid

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
    "Prefer": "wait=25",
}
response = requests.post(
    "https://scifig.ai/api/v1/charts/generations",
    headers=headers,
    files={"data": open("measurements.csv", "rb")},
    data={"request": "Box plot of response by group with individual points", "journal_style": "nature"},
    timeout=60,
)
print(response.status_code, response.json())

AnteriorConversión de imágenes SiguienteCreación y edición de diagramas de flujoDibuja diagramas de flujo científicos y de trabajo en SVG y luego modifícalos con instrucciones adicionales.