# SciFig API 및 MCP 서버

코드 또는 AI 어시스턴트로 과학 그림, 그래프 및 순서도를 만드세요. 사용자용 문서: https://scifig.ai/ko/developers. OpenAPI: https://scifig.ai/api/v1/openapi.json.

## 개요

SciFig API는 웹사이트와 같은 엔진, 가격 및 크레딧으로 과학 그림, 그래프 및 순서도를 생성합니다. 기본 URL은 `https://scifig.ai/api/v1`입니다. 모든 생성은 작업으로 처리되며, 생성 후 상태와 결과를 조회합니다.

AI 어시스턴트는 `https://mcp.scifig.ai/mcp`의 원격 MCP 서버로 SciFig를 사용할 수 있습니다(아래 “MCP 서버” 참조).

## 인증

`/pricing`, `/openapi.json` 및 `/openapi.yaml`을 제외한 모든 요청에 `Authorization: Bearer <credential>`을 보내세요.

- 쓰기 권한이 하나라도 있는 키는 유효한 구독 또는 잔액이 있는 크레딧 팩이 필요하며 유효기간은 30·90·365일입니다. 읽기 전용 키는 만료 없음도 선택할 수 있습니다.
- OAuth 액세스 토큰(`sf_at_…`): 승인 후 MCP 클라이언트에 발급되며 1시간 유효합니다. `offline_access`를 요청한 클라이언트에는 30일간 유효한 갱신 토큰(`sf_rt_…`)도 발급합니다. 설정 → API 키 → 연결된 앱에서 앱의 접근 권한을 취소할 수 있습니다.
- 8개 범위는 각각 선택하며 다른 권한을 포함하지 않습니다. 파일 업로드, 작업 조회, 잔액 조회는 별도 권한이 필요합니다. `images:generate`, `images:edit`, `images:convert`, `charts:generate`, `flowcharts:generate`, `files:write`, `jobs:read`, `credits:read`
- `GET /api/v1/capabilities`는 유효한 인증 정보만 필요하며 업무 범위는 필요하지 않습니다. `granted_scopes`만 반환하고 잔액, 요금제, 계정 정보는 반환하지 않습니다.
- 권한 거부와 다른 오류를 포함한 모든 인증된 호출의 메타데이터를 30일간 보관합니다. 프롬프트, 콘텐츠, 파일명, IP, 인증 정보는 저장하지 않습니다. 플랫폼 장애 시 기록은 최선을 다하나 누락될 수 있습니다. 설정의 키, 호출 기록, 연결 앱은 각각 페이지당 10개입니다. 크레딧은 연결된 작업의 정산 결과이며 재요청 행을 합산하지 마세요.
- 허용된 `CIMD` 클라이언트만 `private_key_jwt`를 사용하며 공개 키 서명과 재전송 방지를 검증합니다. 익명 동적 등록은 여전히 `none` 또는 `client_secret_basic`만 허용합니다.

## 빠른 시작

```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"}'
```

응답은 작업 객체입니다. 아직 완료되지 않았으면 `Location: /api/v1/jobs/{id}`를 포함한 `202`를 반환합니다. 해당 URL을 몇 초 간격으로 폴링하여 `status`가 `succeeded`, `failed` 또는 `canceled`가 되면 `outputs[].download_url`에서 다운로드하세요.

## 공통 규칙

- 요청과 응답은 JSON이며, 업로드 및 그래프 데이터는 `multipart/form-data`입니다. 필드 이름은 `snake_case`입니다.
- 생성하는 모든 `POST`에는 출력 가능한 ASCII 문자 1–255자로 구성된 `Idempotency-Key` 헤더가 필요합니다. 같은 키와 같은 본문으로 재시도하면 같은 작업을 반환하며 중복 과금하지 않습니다. 같은 키에 다른 본문을 보내면 `409 IDEMPOTENCY_CONFLICT`를 반환합니다. 같은 키의 동시 요청은 같은 작업을 반환하거나, 다른 요청을 접수하는 동안 도착한 요청에 `409 IDEMPOTENCY_IN_PROGRESS`를 반환합니다. 거부된 요청(예: `INSUFFICIENT_CREDITS`)은 해당 키에 응답을 유지하므로, 충전 또는 업그레이드 후에는 새 키로 보내세요. 작업이 생성된 뒤 재시도 가능한 오류(`429`, `503`, `409 IDEMPOTENCY_IN_PROGRESS`) 또는 `500 INTERNAL_ERROR`가 발생하면 `details.job_id`가 포함됩니다. 새 키 대신 같은 키로 재시도하거나 `GET /jobs/{job_id}`를 폴링하세요. 접수한 작업을 다시 조회하지 못했으면 `queued` 상태와 `202`로 응답합니다.
- `Prefer: wait=N`(1–30초)은 작업 완료 또는 지정 시간 만료까지 응답을 기다립니다.
- 모든 응답에 `X-Request-Id`가 포함됩니다. 오류는 `{"error": {"code", "message", "request_id", "details"}}` 형식을 사용합니다.
- API는 브라우저의 CORS 호출을 지원하지 않습니다. 서버나 스크립트에서 호출하세요.

## 엔드포인트 및 크레딧

| 엔드포인트 | 용도 | 크레딧 |
| --- | --- | --- |
| POST /images/generations | 과학 그림 생성 | 50 / 75 / 100 (standard / advanced / premium) |
| POST /images/edits | 이미지 편집: 지시(마스크로 한 영역 다시 그리기), 흰색 배경, 화면 비율, 색상 또는 텍스트 교체 | 50 / 75 / 100, 마스크 또는 `replace_text` 사용 시 100 |
| POST /images/text-detections | 교체 전에 이미지 속 텍스트 감지 | 0 |
| POST /images/upscales | 2K, 4K 또는 8K로 업스케일 | 50 / 100 / 150 |
| POST /images/conversions | SVG, PNG, PDF, TIFF 또는 PPTX로 변환(순서도 SVG는 PNG, PDF, TIFF 또는 PPTX로) | SVG는 150, 기타 형식은 무료(하루 200회) |
| POST /charts/generations | CSV, TSV 또는 Excel 데이터로 그래프 작성 | 100 |
| POST /charts/edits | 그래프 최신 버전 수정 | 100 |
| POST /flowcharts/generations | SVG 순서도 작성 | 100 |
| POST /flowcharts/edits | 순서도 최신 버전 수정 | 100 |
| POST /files | 이미지, 마스크 또는 순서도 첨부 파일 업로드 | 0 |
| GET /jobs/{id} | 작업의 상태, 크레딧 및 다운로드 링크 | 0 |
| GET /jobs | 내 최근 작업, 최신순(커서 페이지 나누기) | 0 |
| GET /files/{file_id} | 파일 다운로드 | 0 |
| GET /credits | 잔액, 요금제 및 작업 제한 | 0 |
| GET /pricing | 모든 작업의 크레딧 가격(인증 불필요) | 0 |
| GET /openapi.json | OpenAPI 3.1 명세(인증 불필요) | 0 |
| GET /openapi.yaml | 동일 명세의 YAML 버전 | 0 |

## 요청 필드

`POST /images/generations`: `prompt`(필수), `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`(사전 설정 ID 또는 1–4개의 `#RRGGBB` 색상), `reference_file_ids`(최대 3개). 일부 모델과 참조 이미지에는 유료 요금제가 필요하며 오류에 표시됩니다.

`POST /images/edits`: `image`(`file_id`) 및 `operation`. `instruct`(기본값)는 `instruction`(최대 2000자)과 선택적 `mask`(PNG, 흰색은 변경 영역, 마스크 사용 시 항상 `premium` 모델)를 받습니다. `white_background`는 배경을 단색 흰색으로 바꿉니다. `aspect_ratio`는 이미지를 `aspect_ratio`에 맞춥니다. `recolor`는 `palette`(1–8개의 `#RRGGBB` 색상)를 적용하거나 자동 선택합니다. 이 작업들은 모두 `quality`를 받습니다. `replace_text`는 `text_detection`(동일 이미지의 `POST /images/text-detections`에서 반환한 ID) 및 `replacements`(`[{"index", "text"}]`)를 받고 항상 `premium` 텍스트 편집 모델을 사용합니다.

`POST /images/text-detections`: `image`. `id`, 이미지 `width` 및 `height`, 읽는 순서의 `texts`(`index`, `text`, `corners`)를 반환합니다. 무료이며 웹사이트의 15분당 20회 감지 한도를 공유합니다.

`POST /images/upscales`: `image`, `scale`(`2k`, `4k`는 Starter 이상, `8k`는 Plus 이상 필요. 크레딧 팩 잔액이 0보다 크면 Pro로 간주).

`POST /images/conversions`: `image`, `format`(`svg`, `png`, `pdf`, `tiff`, `pptx`). SVG의 `vector_mode`는 `editable_text`(기본값) 또는 `full_vector`이며, 원본은 PNG, JPEG 또는 WebP입니다. 다른 형식의 `dpi`는 300, 600 또는 1000입니다. DPI는 메타데이터로 기록하고 페이지 크기를 정하며, 픽셀을 다시 샘플링하지 않습니다(더 많은 픽셀이 필요하면 먼저 업스케일). 원본은 PNG, JPEG 또는 순서도 SVG이며, WebP는 지원하지 않고 PNG 및 TIFF에는 PNG 원본이 필요합니다. 순서도 SVG는 서버에서 Arial 및 Noto 글꼴로 렌더링하며, `width`(256–4096, 기본값 2048)가 긴 변의 픽셀 수를 정합니다. 글꼴이 표시할 수 없는 텍스트는 거부합니다. PPTX에는 렌더링한 이미지가 들어가며 편집 가능한 도형은 아닙니다.

`POST /charts/generations`(`multipart`): `data`(CSV, TSV, TXT, XLSX 또는 XLS, 최대 8 MB, 텍스트 파일 구분자는 자동 감지), `request`(그릴 내용, 1–16,000자), 선택 항목 `chart_types`(쉼표 구분), `journal_style`(`default`, `nature`, `science`, `cell`, `plos`, `acs`), `figure_width`(`single`, `onehalf`, `double`), `color_palette`, `sheet_name`(여러 시트가 있는 통합 문서의 워크시트). 읽을 수 없는 데이터는 `details.field = data`와 `details.reason`의 파서 코드를 포함한 `400 INVALID_REQUEST`를 반환합니다. PNG, PDF, TIFF 및 EPS로 출력합니다.

`POST /charts/edits` 및 `POST /flowcharts/edits`: `job`(이전 그래프 또는 순서도 작업)과 `instruction`(그래프 1–16,000자, 순서도 1–8,000자). 해당 작업 결과에서 이어서 편집하며, 그래프의 데이터, 종류 및 학술지 스타일 또는 순서도의 화면 비율을 유지합니다. 작업 공간처럼 최신 버전만 편집할 수 있습니다. 새 버전이 있으면(웹사이트에서 만든 버전 포함) `details.reason = NOT_LATEST_REVISION`을 포함한 `409 REVISION_CONFLICT`를 반환합니다. 상위 작업이 실행 중이면 재시도 가능한 `409 REVISION_CONFLICT`(`PARENT_JOB_RUNNING`, `Retry-After` 포함), 실패했으면 `400 INVALID_REQUEST`(`JOB_NOT_SUCCEEDED`)를 반환합니다.

`POST /flowcharts/generations`: `prompt`(1–8,000자), `aspect_ratio`(`auto` 또는 위 비율 중 하나), 선택적 `attachment_file_ids`(최대 8개, 용도 `flowchart_attachment`로 업로드). SVG로 출력합니다.

## 작업

`status`는 `queued`, `processing`, `succeeded`, `failed` 또는 `canceled`입니다. `credits`는 원장에서 읽은 `reserved`, `charged` 및 `refunded`를 보고합니다. 실패한 작업은 환불됩니다.

시간이 초과된 생성 또는 편집은 `error.code = TASK_TIMED_OUT`과 `late_delivery_until` 시각을 가진 `failed` 상태가 됩니다. 해당 시각까지 무료로 결과가 제공될 수 있으므로 새 작업을 만들지 말고 계속 조회하세요.

콘텐츠 정책 거부는 생성 시 `422 CONTENT_REJECTED`, 또는 실행 중 발생하면 `error.code = CONTENT_REJECTED`가 포함된 `failed` 작업으로 표시됩니다. 두 경우 모두 환불됩니다.

각 결과에는 `file_id`, `format` 및 인증 없이 1시간 동안 사용할 수 있는 `download_url`이 있습니다. PNG는 `width` 및 `height`도 보고합니다. 그래프와 순서도 결과에는 웹사이트 작업 공간에서 여는 `editor_url`이 있으며, 과학 그림과 변환에는 없습니다.

이미지 결과(PNG, JPEG, WebP)는 `file_id`로 이미지 엔드포인트의 `image` 또는 참조 이미지에 전달할 수 있습니다. 변환 원본은 최대 20 MB입니다. PNG, PDF, TIFF 및 PPTX 변환은 PNG, JPEG 이미지와 순서도 SVG를 받으며, WebP는 지원하지 않습니다.

## 파일

`POST /files`(`multipart`): `file` 및 `purpose`(`image`, `mask` 또는 `flowchart_attachment`). 이미지는 최대 20 MB의 PNG, JPEG 또는 WebP, 마스크는 최대 8 MB의 PNG, 순서도 첨부 파일은 최대 32 MB의 FlowChart 작업 공간 지원 형식입니다. 응답은 `201`과 `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at` 및 `created_at`입니다. 업로드 파일은 24시간 사용할 수 있습니다. 웹사이트 업로드 한도를 공유하며, 초과하면 `429 RATE_LIMITED`를 반환합니다. 선택적 `Idempotency-Key`(출력 가능한 ASCII 문자 1–255자)로 업로드를 재요청할 수 있습니다. 같은 계정, 키, `purpose`는 다시 업로드하거나 한도를 소모하지 않고 첫 파일을 `201`로 반환합니다. 같은 키와 `purpose`에 다른 바이트를 보내면 `409 IDEMPOTENCY_CONFLICT`를 반환합니다. 만료된 업로드를 재요청하면 `details.reason = FILE_EXPIRED`가 포함된 `400 INVALID_REQUEST`를 반환하므로 새 키로 다시 업로드하세요.

`GET /files/{file_id}`는 인증 정보 또는 작업의 서명된 `download_url`로 내 파일을 다운로드합니다. 만료되거나 변경된 서명 링크는 `404`를 반환하며, 이용 정지 또는 삭제 중인 계정의 모든 링크도 마찬가지입니다.

## 오류

| 코드 | HTTP | 의미 |
| --- | --- | --- |
| UNAUTHORIZED | 401 | 인증 정보가 없거나 유효하지 않습니다. |
| ACCOUNT_UNAVAILABLE | 401 | 이 계정은 API를 사용할 수 없습니다. |
| SCOPE_DENIED | 403 | 이 인증 정보에는 해당 권한이 없습니다. |
| INVALID_REQUEST | 400 | 요청이 유효하지 않습니다. |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Idempotency-Key 헤더(출력 가능한 ASCII 문자 1–255자)가 필요합니다. |
| IDEMPOTENCY_CONFLICT | 409 | 이 Idempotency-Key는 이미 다른 요청에 사용되었습니다. |
| IDEMPOTENCY_IN_PROGRESS | 409 | 이 Idempotency-Key의 요청은 아직 처리 중입니다. |
| NOT_FOUND | 404 | 찾을 수 없습니다. |
| REVISION_CONFLICT | 409 | 현재 그래프 또는 순서도 작업을 편집할 수 없습니다: `NOT_LATEST_REVISION`, `EDIT_IN_PROGRESS` 또는 상위 작업이 실행 중인 경우의 `PARENT_JOB_RUNNING`. |
| PAYLOAD_TOO_LARGE | 413 | 요청 본문이 너무 큽니다. |
| INSUFFICIENT_CREDITS | 402 | 크레딧이 부족합니다. |
| CONTENT_REJECTED | 422 | 콘텐츠 정책이 요청을 거부했습니다. 생성 시에는 `422`, 실행 중이면 실패 작업의 `error.code`로 반환하며, 두 경우 모두 환불됩니다. |
| PLAN_REQUIRED | 403 | 현재 요금제에는 이 옵션이 포함되지 않습니다. |
| RATE_LIMITED | 429 | 요청 수, 시간당 작업 수, 일일 변환 수 또는 업로드 수를 초과했습니다. `details.reason`이 해당 원인을 표시합니다. |
| CONCURRENCY_LIMITED | 429 | 이 계정에서 실행 중인 작업이 너무 많습니다. |
| SERVICE_UNAVAILABLE | 503 | 서비스를 일시적으로 사용할 수 없습니다. 같은 Idempotency-Key로 재시도하세요. |
| TASK_FAILED | 502 | 작업이 실패하여 크레딧이 환불되었습니다. 다시 시도하려면 새 Idempotency-Key로 새 요청을 보내세요. |
| INTERNAL_ERROR | 500 | 내부 오류. |

`details.reason`은 `INVALID_REQUEST`, `PLAN_REQUIRED` 등의 정확한 원인을 표시합니다. `details.top_up_url`은 `INSUFFICIENT_CREDITS`에만 포함되며, `utm_source`는 요청 경로에 따라 `api` 또는 `mcp`입니다.

실패한 작업 내부에만 나타나는 코드:

| error.code | 의미 | 대처 방법 |
| --- | --- | --- |
| TASK_TIMED_OUT | 작업 시간이 초과되어 환불되었습니다. 과학 그림 생성 또는 편집에 `late_delivery_until`이 포함되면 해당 시각까지 무료로 결과가 도착할 수 있습니다. | `late_delivery_until`까지 작업을 계속 조회. 그 외에는 새 키로 새 요청 전송 |
| CONTENT_REJECTED | 작업 실행 중 콘텐츠 정책이 결과를 거부했으며 환불되었습니다. 생성 시 요청 자체가 거부되면 같은 코드를 `422`로 반환합니다. | 프롬프트 또는 입력을 변경하고 새 키 사용 |
| ADMISSION_INCOMPLETE | 재시도 가능한 오류로 작업이 시작되지 않았습니다. 크레딧은 사용하지 않았습니다. | 같은 요청을 같은 Idempotency-Key로 전송 |
| TASK_NOT_FOUND | 작업이 접수되었지만 해당 작업 데이터를 더 이상 찾을 수 없습니다. | 새 키로 새 요청 전송 |
| TASK_FAILED | 작업이 실패하여 환불되었습니다. 별도 공개 코드가 없는 모든 엔진 장애는 `TASK_FAILED`로 표시하며, 엔진 코드는 `details.reason`에 포함됩니다. | 새 키로 새 요청 전송 |
| INTERNAL_ERROR | 작업이 이유를 보고하지 않고 실패했으며 환불되었습니다. | 새 키로 새 요청 전송 |

## 호출 제한

- 생성: 인증 정보별 분당 20건, 계정별 분당 40건. OAuth 인증 정보는 클라이언트와 계정 조합으로 집계합니다.
- 조회: 인증 정보별 분당 120건.
- 실행 중인 작업 수는 요금제를 따르며, 시간당 최대 200개의 작업을 시작할 수 있습니다. 두 한도 모두 웹사이트와 공유합니다.
- 인증 및 범위 검사를 통과한 응답에는 `X-RateLimit-Limit`, `X-RateLimit-Remaining` 및 `X-RateLimit-Reset`이 포함되며, `429`에는 `Retry-After`가 포함됩니다.
- `429 RATE_LIMITED`에는 여러 원인이 있습니다. `details.reason`과 [호출 제한 페이지](/ko/docs/api/rate-limits)를 확인하세요.

## SciFig 공식 플러그인 설치하기

Claude Code에 SciFig 마켓플레이스를 추가하면 원격 MCP 연결과 설정, 과학 그림, 그래프, 내보내기를 위한 워크플로 스킬 4개를 설치할 수 있습니다.

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

- [API 및 MCP 개요](/ko/developers)
- [MCP 설치 가이드](/ko/developers/mcp/install.md)
- [API 참조 문서](/ko/docs/api)
- [공식 플러그인 살펴보기](https://github.com/lilingm963/scifig-plugins)
- [MCP Registry 등록 정보](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.lilingm963%2Fscifig/versions/1.0.0)

## MCP 서버

서버 URL: `https://mcp.scifig.ai/mcp`(Streamable HTTP). OAuth 지원 클라이언트는 SciFig에 로그인하고 접근을 승인하여 연결합니다. 헤더를 보낼 수 있는 클라이언트는 API 키를 `Authorization: Bearer sk_live_…`로 사용할 수 있습니다.

| 도구 | 기능 |
| --- | --- |
| generate_figure | 프롬프트로 과학 그림 생성 |
| edit_figure | 이미지 편집: 지시(선택적으로 마스크 영역), 흰색 배경, 화면 비율, 색상 또는 텍스트 교체 |
| detect_text | 교체 전에 이미지 속 텍스트 감지 |
| upscale_figure | 2K, 4K 또는 8K로 업스케일 |
| convert_figure | SVG, PNG, PDF, TIFF 또는 PPTX로 변환 |
| generate_chart | CSV 또는 TSV 텍스트나 JSON 행으로 그래프 작성(최대 1 MB) |
| edit_chart | 그래프 최신 버전 수정 |
| generate_flowchart | SVG 순서도 작성, 선택적으로 최대 8개 첨부 파일 사용 |
| edit_flowchart | 순서도 최신 버전 수정 |
| get_job | 작업 상태, 크레딧 및 다운로드 링크 |
| list_figures | 최근 작업 |
| get_credit_balance | 크레딧 잔액, 요금제 및 제한 |

생성 도구는 최대 25초 동안 기다립니다. 작업이 아직 실행 중이면 나중에 `get_job`을 호출하세요. 생성 도구를 다시 호출하면 새 작업이 생성되고 과금됩니다. 결과에는 각 다운로드 링크와 그래프 및 순서도를 SciFig 편집기에서 여는 링크가 표시됩니다.

초기화는 `/capabilities`를 사용하며 `credits:read`가 필요하지 않습니다. 각 도구는 해당 범위가 필요합니다. 외부 URL 또는 data URL 업로드는 `files:write`도 필요하며 가져오기 전에 확인합니다. `file_id` 재사용에는 필요하지 않습니다. 인라인 다운로드와 `get_job`은 `jobs:read`가 필요합니다. 없으면 작업 결과를 보존하고 제한을 설명하며 동의 없이 권한을 확대하지 않습니다.

## 클라이언트 연결

Claude(claude.ai 및 Claude Desktop): 설정 → 커넥터 → 사용자 지정 커넥터 추가에서 서버 URL을 입력한 뒤, SciFig에 로그인하고 접근을 허용하세요.

ChatGPT의 `Plugins`에서 사용자 지정 비공개 MCP 연결을 추가하세요. 메뉴는 계정에 따라 다릅니다.

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

Cursor의 `Customize` → MCP에서 기존 서버를 보존하며 `mcp.json`을 편집하세요. 이후 `Authenticate`를 선택하고 브라우저에서 SciFig를 승인하세요.

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

OAuth를 지원하지 않는 클라이언트는 설정 → API 키의 API 키로 `Authorization: Bearer sk_live_…` 헤더를 추가할 수 있습니다.