API 참조 문서
작업 및 대기 시간 제한
작업 상태, 크레딧 및 결과를 조회하고 폴링 없이 작업을 기다리세요.
작업 조회#
GET /jobs/{id}(범위 figures:read)는 생성 요청과 같은 작업 객체를 반환합니다. 다른 계정의 작업과 알 수 없는 ID는 모두 404 NOT_FOUND를 반환합니다. GET /jobs?limit=10&cursor=…는 내 작업을 최신순으로 나열합니다(페이지당 1–20건, 다음 페이지는 next_cursor 사용).
{
"id": "5f4a9a5e-fc45-4eae-9f9c-56b5f686cba5",
"kind": "chart",
"status": "succeeded",
"created_at": "2026-10-14T11:20:05.000Z",
"credits": { "reserved": 50, "charged": 50, "refunded": 0 },
"outputs": [
{
"file_id": "0b7c…",
"format": "png",
"width": 2126,
"height": 1417,
"download_url": "https://scifig.ai/api/v1/files/0b7c…?exp=…&sig=…",
"expires_at": "2026-10-14T12:21:40.000Z",
"editor_url": "https://scifig.ai/app/datachart?conversation=…"
}
],
"error": null
}kind는 image_generation, image_edit, image_upscale, image_conversion, chart 또는 flowchart입니다. 응답에는 프롬프트, 입력 데이터 또는 내부 식별자가 포함되지 않습니다.
| 출력 필드 | 있음 | 의미 |
|---|---|---|
| file_id | always | 다른 엔드포인트 또는 GET /files/{file_id}에 전달 |
| format | always | png, svg 또는 pdf 등 결과의 파일 확장자 |
| width, height | PNG 결과 | 픽셀 크기 |
| download_url, expires_at | always | 서명된 링크, 유효 기간 1시간 |
| editor_url | 그래프 및 순서도 작업 | 웹사이트 작업 공간에서 결과 열기. 과학 그림과 변환에는 없음 |
상태 전이#
| status | 의미 |
|---|---|
| queued | 접수 완료, 실행 여유를 기다리는 중 |
| processing | 실행 중 |
| succeeded | 완료. outputs가 준비되었으며 크레딧 차감 완료 |
| failed | 결과를 생성하지 못함. error.code가 이유를 표시하며 예약 크레딧 반환 |
| canceled | 완료 전에 중단, 환불 완료 |
| 실패한 작업의 `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 | 작업이 이유를 보고하지 않고 실패했으며 환불되었습니다. | 새 키로 새 요청 전송 |
succeeded, failed 및 canceled는 최종 상태이지만 한 가지 예외가 있습니다. TASK_TIMED_OUT으로 실패한 과학 그림 생성 또는 편집에는 late_delivery_until이 포함됩니다. 그 시각까지는 결과가 무료로 도착하고 작업이 succeeded로 바뀔 수 있습니다. 새 작업을 만들지 말고 기존 작업을 계속 조회하세요.
목록의 작업 중 하나라도 조회할 수 없으면 GET /jobs는 Retry-After: 3이 포함된 503 SERVICE_UNAVAILABLE을 반환합니다. 목록 요청을 재시도하세요. 해당 작업을 실패 결과로 대체하지 않습니다.
대기 시간 제한#
- 생성 요청에
Prefer: wait=N(1–30)을 지정하면 작업이 최종 상태가 되거나 N초가 지날 때까지 응답을 기다립니다. 최종 상태의 작업은200, 아직 실행 중인 작업은Location: /api/v1/jobs/{id}와Retry-After를 포함한202를 반환합니다. - 대기는 작업을 변경하지 않습니다.
202는 오류가 아니며, 응답 후에도 작업은 계속 실행됩니다. GET /jobs/{id}는Retry-After(3초)보다 빠르게 폴링하지 마세요. 과학 그림은 보통 20–90초, 그래프와 순서도는 30–120초에 완료됩니다.- 실패한 작업은 거부된 요청을 기록할 수도 있습니다.
402 INSUFFICIENT_CREDITS또는422 CONTENT_REJECTED같은 오류로 거부된 생성 요청은 해당 코드와 크레딧 사용 없이failed작업으로GET /jobs에 남습니다. - 서버 연동에서는 대기 전에 작업 ID를 저장하여 연결이 끊겨도 두 번째 작업을 만들지 않도록 하세요.
cURL#
curl https://scifig.ai/api/v1/jobs/<job_id> \
-H "Authorization: Bearer $SCIFIG_API_KEY"JavaScript#
const response = await fetch('https://scifig.ai/api/v1/jobs/<job_id>', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
},
});
const result = await response.json();
console.log(response.status, result);Python#
import os
import requests
headers = {
"Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.get(
"https://scifig.ai/api/v1/jobs/<job_id>",
headers=headers,
timeout=60,
)
print(response.status_code, response.json())