# 그래프 생성 및 편집

데이터로 출판용 그래프를 만들고 후속 지시로 수정하세요.

출처: https://scifig.ai/ko/docs/api/charts

## 폼 필드

`POST /charts/generations`는 `multipart/form-data`를 받습니다. 필요한 범위: `figures:generate`.

| 필드 | 유형 | 필수 | 기본값 | 규칙 |
| --- | --- | --- | --- | --- |
| data | file | 예 | — | 머리글 행이 있는 CSV, TSV, TXT, XLSX 또는 XLS, 최대 8 MB. CSV, TSV, TXT 구분자(쉼표, 탭 또는 세미콜론)는 자동 감지 |
| request | string | 예 | — | 그릴 내용을 자연어로 설명, 1–16,000자 |
| chart_types | string | 아니요 | 데이터에서 선택 | 쉼표로 구분하거나 JSON 배열 사용. 아래 목록 참조 |
| journal_style | string | 아니요 | `default` | `default`, `nature`, `science`, `cell`, `plos` 또는 `acs` |
| figure_width | string | 아니요 | `double` | `single`, `onehalf` 또는 `double` 단 너비. PLOS 및 ACS는 `onehalf` 미지원 |
| color_palette | string | 아니요 | `okabe_ito` | `okabe_ito`, `wong`, `tol_bright`, `tol_muted`, `nature`, `science`, `nejm`, `lancet` 또는 `jama` |
| sheet_name | string | 여러 시트가 있는 통합 문서에 사용 | — | XLSX 또는 XLS에서 그래프에 사용할 워크시트 이름(1–255자) |

## 데이터 오류

- 무언가를 생성하기 전에 웹사이트와 동일한 파서로 데이터를 분석합니다. 읽을 수 없는 데이터는 `details.field = data`와 `details.reason`의 파서 코드(예: `DATACHART_CSV_INVALID`, `DATACHART_TOO_MANY_ROWS`)를 포함한 `400 INVALID_REQUEST`를 반환합니다. 작업이 실행되지 않으며 크레딧도 사용하지 않습니다.
- 여러 시트가 있는 통합 문서에 `sheet_name`이 없으면 `details.sheet_names`에 시트 이름을 포함한 `400 INVALID_REQUEST`(`DATACHART_WORKSHEET_REQUIRED`)를 반환합니다. `sheet_name`을 지정해 다시 요청하세요. 존재하지 않는 `sheet_name`은 `DATACHART_WORKSHEET_INVALID`를 반환하며, 이때도 `details.sheet_names`가 포함됩니다.
- 지원 목록에 없는 형식은 `UNSUPPORTED_DATA_FORMAT`, 크기 제한을 초과한 파일은 `DATA_FILE_TOO_LARGE`를 반환합니다.
- 새 데이터 파일마다 웹사이트의 업로드 한도에 집계됩니다. 초과하면 `429 RATE_LIMITED`(`UPLOAD_RATE_LIMITED` 또는 `UPLOAD_DAILY_LIMIT_REACHED`)를 반환합니다. 같은 키로 재시도해도 파일을 다시 집계하지 않습니다.

## 그래프 종류

`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`

## 출력 및 크레딧

그래프당 100 크레딧입니다. 성공한 작업에는 같은 그림의 PNG, PDF, TIFF 및 EPS 결과가 포함되며, 학술지의 열 너비에 맞춰 크기를 지정합니다. 각 결과의 `editor_url`로 웹사이트 DataChart 대화에서 그래프를 열 수 있습니다.

## 편집

JSON `{"job": "<chart job id>", "instruction": "..."}`을 포함한 `POST /charts/edits`는 해당 작업의 그래프를 수정하며, 데이터, 그래프 종류, 학술지 스타일 및 팔레트를 유지합니다. `instruction`은 1–16,000자입니다. 작업 공간과 동일하게 100 크레딧이 듭니다.

- 내 그래프 작업이 아니면 `400 INVALID_REQUEST`(`JOB_NOT_FOUND`)를 반환합니다. 실패한 작업이면 `400 INVALID_REQUEST`(`JOB_NOT_SUCCEEDED`)를 반환합니다.
- 아직 실행 중이면 `details.reason = PARENT_JOB_RUNNING`과 `Retry-After`가 포함된 `409 REVISION_CONFLICT`를 반환합니다. 이 경우는 재시도할 수 있으므로, 작업이 완료되면 같은 요청을 같은 키로 보내세요.
- 작업 공간과 동일하게 최신 버전만 편집할 수 있습니다. 연결된 작업 중 가장 최신 작업을 편집하세요. 이전 작업은 `409 REVISION_CONFLICT`(`NOT_LATEST_REVISION`)를 반환합니다. 웹사이트에서 새 버전을 만들었거나 같은 버전의 다른 편집이 먼저 접수된 경우도 마찬가지입니다.
- 편집은 한 번에 하나만 실행됩니다. 현재 버전의 편집이 실행 중이면 다른 편집은 `409 REVISION_CONFLICT`(`EDIT_IN_PROGRESS`)를 반환합니다. 실행 중인 작업을 기다린 뒤 그 결과를 편집하세요.
- 현재 그래프 형식 이전에 웹사이트에서 만든 그래프는 API로 이어서 편집할 수 없습니다: `400 INVALID_REQUEST`(`JOB_NOT_EDITABLE`).
- API로 편집한 결과는 웹사이트의 동일한 DataChart 대화에 표시됩니다.

## cURL

```bash
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

```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

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