# 작업 및 대기 시간 제한

작업 상태, 크레딧 및 결과를 조회하고 폴링 없이 작업을 기다리세요.

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

## 작업 조회

`GET /jobs/{id}`(범위 `figures:read`)는 생성 요청과 같은 작업 객체를 반환합니다. 다른 계정의 작업과 알 수 없는 ID는 모두 `404 NOT_FOUND`를 반환합니다. `GET /jobs?limit=10&cursor=…`는 내 작업을 최신순으로 나열합니다(페이지당 1–20건, 다음 페이지는 `next_cursor` 사용).

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

```bash
curl https://scifig.ai/api/v1/jobs/<job_id> \
  -H "Authorization: Bearer $SCIFIG_API_KEY"
```

## JavaScript

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

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