# ジョブと待機時間の上限

ジョブのステータス、クレジット、出力を読み取り、ポーリングせずに完了を待てます。

出典：https://scifig.ai/ja/docs/api/jobs

## ジョブの取得

`GET /jobs/{id}`（スコープ `figures:read`）は作成リクエストと同じジョブオブジェクトを返します。他のアカウントのジョブや未知の ID は、どちらも `404 NOT_FOUND` を返します。`GET /jobs?limit=10&cursor=…` は自分のジョブを新しい順に表示します（1 ページ 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())
```