API リファレンス
クレジット
API は SciFig のクレジットを使用します。ウェブサイト、API、MCP で 1 つの残高を共有します。
残高の取得#
GET /credits（スコープ figures:read）は残高、実行中ジョブが確保したクレジット、プラン、タスク制限を返します：
{
"balance": 2950,
"reserved": 100,
"granted_scopes": ["figures:read", "figures:generate"],
"plan": "plus",
"plan_level": 2,
"limits": { "concurrent_tasks": 5, "tasks_per_hour": 200 },
"top_up_url": "https://scifig.ai/pricing?utm_source=api"
}planはfree、starter、plus、proのいずれかです。クレジットパック残高が 0 を超えるアカウントは、その残高がある間はproとして扱います。tasks_per_hourはすべてのプランで 200、concurrent_tasksはプランによって異なります。top_up_urlは API への直接リクエストではutm_source=api、MCP サーバー経由ではutm_source=mcpを含みます。granted_scopesは現在の認証情報の権限を示します。figures:readと、許可されている場合はfigures:generateが含まれます。
GET /pricing は認証なしで全料金を返します。この文書の料金も同じ表から取得しています。API 専用プランはありません。料金ページでクレジットまたはサブスクリプションを購入してください。
クレジット確保の流れ#
- ジョブ作成時に料金分を原子的に確保するため、2 つのリクエストが同じクレジットを使用することはありません。
- 残高不足の場合は
details.top_up_url付きの402 INSUFFICIENT_CREDITSを返します。クレジットは確保されず、処理も実行しません。拒否されたリクエストはそのエラーを持つ失敗ジョブとしてGET /jobsに残り、同じキーで再送すると同じ応答を返します。 - 成功したジョブは確保したクレジットを一度だけ課金し、失敗またはキャンセルしたジョブは全額返還します。内部の再試行は再確保せず、
Idempotency-Keyの再送も元の確保を再利用します。 - 各ジョブの
credits.reserved、credits.charged、credits.refundedは台帳から取得します。 - クレジットはウェブサイトと同じ順番で消費します。有効期限の近いものから使い、期限のないパックのクレジットは最後に使います。
cURL#
curl https://scifig.ai/api/v1/credits \
-H "Authorization: Bearer $SCIFIG_API_KEY"JavaScript#
const response = await fetch('https://scifig.ai/api/v1/credits', {
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/credits",
headers=headers,
timeout=60,
)
print(response.status_code, response.json())