API リファレンス
ジョブと待機時間の上限
ジョブのステータス、クレジット、出力を読み取り、ポーリングせずに完了を待てます。
ジョブの取得#
GET /jobs/{id}（スコープ figures:read）は作成リクエストと同じジョブオブジェクトを返します。他のアカウントのジョブや未知の ID は、どちらも 404 NOT_FOUND を返します。GET /jobs?limit=10&cursor=… は自分のジョブを新しい順に表示します（1 ページ 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())