Référence API

Création et modification de graphiques

Tracez des graphiques prêts à publier à partir de vos données, puis modifiez-les avec de nouvelles instructions.

Champs du formulaire#

POST /charts/generations accepte multipart/form-data. Portée requise : figures:generate.

Champ	Type	Obligatoire	Valeur par défaut	Règles
data	file	oui	—	CSV, TSV, TXT, XLSX ou XLS jusqu’à 8 MB, avec une ligne d’en-tête ; le séparateur des CSV, TSV et TXT, virgule, tabulation ou point-virgule, est détecté
request	string	oui	—	Ce qu’il faut tracer, en langage courant ; de 1 à 16 000 caractères
chart_types	string	non	choisi à partir des données	Valeurs séparées par des virgules ou tableau JSON ; voir la liste ci-dessous
journal_style	string	non	`default`	`default`, `nature`, `science`, `cell`, `plos` ou `acs`
figure_width	string	non	`double`	Largeur de colonne `single`, `onehalf` ou `double` ; PLOS et ACS n’ont pas de `onehalf`
color_palette	string	non	`okabe_ito`	`okabe_ito`, `wong`, `tol_bright`, `tol_muted`, `nature`, `science`, `nejm`, `lancet` ou `jama`
sheet_name	string	pour les classeurs comportant plusieurs feuilles	—	La feuille du fichier XLSX ou XLS à utiliser pour le graphique ; de 1 à 255 caractères

Erreurs de données#

Les données sont analysées avant toute création, avec le même analyseur que sur le site. Des données illisibles renvoient 400 INVALID_REQUEST avec details.field = data et le code de l’analyseur dans details.reason, par exemple DATACHART_CSV_INVALID ou DATACHART_TOO_MANY_ROWS. Aucune tâche n’est exécutée et aucun crédit n’est utilisé.
Un classeur comportant plusieurs feuilles sans sheet_name renvoie 400 INVALID_REQUEST avec DATACHART_WORKSHEET_REQUIRED et les noms des feuilles dans details.sheet_names. Renvoyez la requête avec sheet_name. Un sheet_name inconnu renvoie DATACHART_WORKSHEET_INVALID, également avec details.sheet_names.
Un type de fichier absent de la liste renvoie UNSUPPORTED_DATA_FORMAT ; un fichier dépassant la taille limite renvoie DATA_FILE_TOO_LARGE.
Chaque nouveau fichier de données compte dans les limites d’importation du site ; au-delà, la réponse est 429 RATE_LIMITED avec UPLOAD_RATE_LIMITED ou UPLOAD_DAILY_LIMIT_REACHED. Réessayer avec la même clé ne compte pas le fichier à nouveau.

Types de graphiques#

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

Résultats et crédits#

100 crédits par graphique. Une tâche réussie fournit la même figure en PNG, PDF, TIFF et EPS, dimensionnée pour la colonne de la revue. Chaque résultat contient un editor_url, qui ouvre le graphique dans sa conversation DataChart sur le site.

Modifications#

POST /charts/edits avec le JSON {"job": "<chart job id>", "instruction": "..."} modifie le graphique produit par la tâche en conservant ses données, ses types de graphiques, son style de revue et sa palette. instruction contient de 1 à 16 000 caractères. 100 crédits, comme dans l’espace de travail.

La tâche doit être l’une de vos tâches de graphique, sinon 400 INVALID_REQUEST avec JOB_NOT_FOUND. Si elle a échoué, la réponse est 400 INVALID_REQUEST avec JOB_NOT_SUCCEEDED.
Si elle est encore en cours, la réponse est 409 REVISION_CONFLICT avec details.reason = PARENT_JOB_RUNNING et Retry-After. Cette erreur permet une nouvelle tentative : envoyez la même requête avec la même clé une fois la tâche terminée.
Seule la version la plus récente peut être modifiée, comme dans l’espace de travail. Modifiez la tâche la plus récente de la chaîne ; une version antérieure renvoie 409 REVISION_CONFLICT avec NOT_LATEST_REVISION, également si une nouvelle version a été créée sur le site ou si une autre modification de la même version a été acceptée en premier.
Une seule modification à la fois : tant qu’une modification de la version actuelle est en cours, une autre renvoie 409 REVISION_CONFLICT avec EDIT_IN_PROGRESS. Attendez la tâche en cours, puis modifiez son résultat.
Un graphique créé sur le site avant le format actuel ne peut pas être poursuivi via l’API : 400 INVALID_REQUEST avec JOB_NOT_EDITABLE.
Les modifications effectuées via l’API apparaissent dans la même conversation DataChart sur le site.

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())

PrécédentConversion d’images SuivantCréation et modification de diagrammes de fluxDessinez des diagrammes de flux scientifiques et des diagrammes de flux de travail en SVG, puis modifiez-les avec de nouvelles instructions.