PUBLIC API · 更新 2026-09-21
APIドキュメント
商品写真から商品を特定し、相場の根拠を集め、人が確認・修正できる非同期APIです。
https://priceapi.tuskey.one2.0.1price-api-1gemini-3.5-flash確認UIは /_ui/。相場計算はJPTC Lister v0.11.74を使用します。出力は市場参考値と状態調整候補で、最終の販売価格・送料・手数料・精算額ではありません。
バージョンの管理
api_version: "2.0.1" がPrice-API自身のリリース番号です。互換性を壊す変更は先頭、互換性を保つ機能追加は中央、不具合修正は末尾の番号を更新します。schema_version は結果形式、engine_version は内部計算エンジンの版です。URLの /v1 はAPIパスの世代なので、アプリ番号とは別に維持します。
認証・ユーザー分離
GET /v1/healthz を除くAPIに、X-API-Key ヘッダーを付けます。このドキュメントと確認UIのページ自体はログインなしで開けます。
X-API-Key: <管理者から受領したキー>- Tuskey等の連携サービスはサーバー側から呼び出す構成にしてください。CORSは無効です。共有キーをブラウザのコードへ埋め込みません。
- ジョブの所有権はAPIキー単位です。他のキーのジョブは404になります。
external_user_idは管理・絞り込み用ラベルです。ユーザー認証や権限確認の代わりにはなりません。連携側でログインユーザーとジョブを対応させてください。- 既定の制限はキーごとに60リクエスト/分。キーの値をURLやログに含めないでください。
最短の実装例
①画像を送信 → ②状態を約5秒間隔で確認 → ③完了後に結果を取得します。所要時間は画像・外部サイトの応答により変わります。
下記はNode.js 20以上のサーバー用 .mjs の例です。PRICE_API_KEY はサーバーの環境変数へ設定し、item.jpg を対象画像に置き換えます。
import { readFile } from 'node:fs/promises';
const base = 'https://priceapi.tuskey.one';
const key = process.env.PRICE_API_KEY;
if (!key) throw new Error('PRICE_API_KEY is required');
async function api(path, options = {}) {
const response = await fetch(base + path, {
...options,
headers: { 'X-API-Key': key, ...options.headers },
signal: AbortSignal.timeout(60000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
const form = new FormData();
form.append('images', new Blob([await readFile('item.jpg')], {
type: 'image/jpeg'
}), 'item.jpg');
form.append('external_user_id', 'your-user-id');
const created = await api('/v1/jobs', { method: 'POST', body: form });
// created.job_idを自分のDBに保存。通信切断後もこのIDから再取得します。
const deadline = Date.now() + 10 * 60 * 1000;
let job;
while (Date.now() < deadline) {
job = await api(`/v1/jobs/${created.job_id}`);
if (!['queued', 'running'].includes(job.status)) break;
await new Promise(resolve => setTimeout(resolve, 5000));
}
if (!['succeeded', 'partial'].includes(job?.status)) {
throw new Error(`未完了または失敗: ${created.job_id} / ${job?.status}`);
}
const result = await api(`/v1/jobs/${created.job_id}/results`);
console.log({
job_id: created.job_id,
price_usd: result.market?.market_usd,
needs_review: result.needs_review
});これは最小例です。実装時は429の待機、通信失敗の再取得、失敗状態の画面表示を加えてください。POSTの自動再送は重複ジョブを作る可能性があります。partial でも結果は取得できます。
エンドポイント一覧
| メソッド | パス | 用途/正常応答 |
|---|---|---|
| POST | /v1/jobs | 商品登録 · 202 |
| GET | /v1/jobs | 一覧 · 200 |
| GET | /v1/jobs/{id} | 状態 · 200 |
| GET | /v1/jobs/{id}/results | 結果 · 200 |
| GET | /v1/jobs/{id}/review | 処理ログ・編集用データ · 200 |
| PATCH | /v1/jobs/{id}/review | 編集・再計算 · 200 |
| POST | /v1/jobs/{id}/research | 商品情報を使って相場再取得 · 202 |
| POST | /v1/jobs/{id}/cancel | 中止 · 200 |
| GET | /v1/jobs/{id}/image?i=0 | 画像バイナリ · 200 |
| GET | /v1/healthz | プロセス生存 · 200、認証不要 |
| GET | /v1/readyz | DB・Redis・workerの準備確認 · 200/503 |
| GET | /v1/capabilities | 稼働版・モデル・対応機能 · 200 |
POST /v1/jobs
multipart/form-data推奨。 JPEG / PNG / WebPを1〜5枚、1枚10MB以下で送信します。複数画像は同じファイルフィールドを繰り返してください。Content-TypeのboundaryはHTTPライブラリに生成させます。
| フィールド | 形式・制約 |
|---|---|
| image / images / images[] | 画像ファイル。multipartで受け付ける名前 |
| must_include | 手がかり。改行またはカンマ区切り、最大5個・各80文字 |
| external_user_id | 任意。空文字不可、最大128文字 |
| sites | カンマ区切り。既定はyahoo_auction,ebay,mercari,rakuten,suruga_ya。現在の商品解析フローでは駿河屋を補完するため、指定から省いても実行対象になる |
| languages | ja / en、カンマ区切り。既定ja,en。現在の商品特定フローは日英両方の情報を生成する |
| model | 省略推奨。gemini-3.5-flash / gemini-2.5-flash / gemini-2.5-flash-lite / gemini-2.5-pro。受付可能でもプロバイダでの利用可否・品質を保証しない |
| metadata | JSON文字列。review_optionsで自社状態・価格設定を指定 |
metadataの例
{
"review_options": {
"condition_note": "動作未確認、元箱なし",
"self_condition": { "box": "なし", "tested": "未確認" },
"settings": { "cond_pricing_enabled": 1 }
}
}JSON方式
Content-Type: application/json にして次の形式でも送信できます。JSONでは must_include / sites / languages は文字列の配列、metadata はオブジェクトです。
{
"images": [{ "base64": "<画像のBase64データ>" }],
"must_include": ["BEHRINGER", "X2222USB"],
"external_user_id": "your-user-id"
}単数なら image: {"base64":"..."} も可。画像URLからの代理取得と callback_url は未対応で400を返します。
202の応答例
{
"job_id": "job_<ULID>",
"status": "queued",
"created_at": "2026-09-21T00:00:00.000Z",
"model": null,
"must_include": ["BEHRINGER", "X2222USB"],
"external_user_id": "your-user-id",
"poll_url": "/v1/jobs/job_<ULID>",
"image_count": 1
}例中のID・時刻は説明用です。model:null はサーバーの既定モデルを使う指定です。実際のモデルはcapabilitiesやreviewの処理ログを確認してください。
進行状況・結果取得
GET /v1/jobs/{id} を4〜5秒間隔で取得します。状態・開始/完了時刻・画像枚数・管理ラベル等を返します。この応答の result は常にnullです。結果は必ず /results から取得します。
| status | 意味 | 次の操作 |
|---|---|---|
| queued / running | 待機/処理中 | 状態の取得を続ける。reviewで途中経過を表示可 |
| succeeded | 処理終了 | resultsを取得 |
| partial | 処理終了・要確認 | resultsを取得し警告と根拠を表示 |
| failed | 処理失敗 | reviewを確認。商品手修正または商品登録 |
| canceled | 中止 | 自動再開しない。必要なら商品登録 |
レスポンスの読み方
GET /v1/jobs/{id}/results はsucceeded / partialのとき200。それ以外は409です。新形式の主要フィールドは次のとおりです。
{
"job_id": "job_<ULID>",
"status": "partial",
"revision": 18,
"api_version": "2.0.1",
"schema_version": "price-api-1",
"engine_version": "0.11.74",
"product": {
"title_ja": "ベリンガー XENYX X2222USB アナログミキサー",
"title_en": "Behringer XENYX X2222USB Analog Mixer",
"brand": "Behringer", "model": "XENYX X2222USB",
"confidence": 0.95, "category": "audio",
"box_condition": "loose", "condition_class": "used",
"condition_tier": "good", "pack_count": 1, "jan": "",
"condition_notes": "動作・付属品は未確認",
"description_ja": "アナログミキサーです。",
"description_en": "An analog mixer.",
"item_specifics": { "Brand": "Behringer", "Model": "X2222USB" },
"warnings": ["付属品の有無は未確認です"]
},
"fx": { "rate": 157.89, "sgd": 1.2784, "date": "2026-09-18", "source": "frankfurter" },
"market": {
"U": 199.99, "U_strong": null, "J": 120.34,
"J_landed": 154.78, "F": null, "market_usd": 199.99,
"site_values": {}, "flags": [], "basis_mode": "evidence",
"path": "日本側アンカーとeBay販売中の高い方を採用"
},
"condition_pricing": { "ok": false, "price": null, "reason": "状態差調整OFF" },
"evidence": [],
"sources": { "rakuten": { "status": "ok", "count": 30 } },
"warnings": ["成約日が不明な候補があります"],
"needs_review": true,
"identification_confirmed": false
}上は構造説明用の省略例です。数値は本番検証時点の例で、現在の価格や全フィールドを保証するものではありません。通常は keywords、updated_at、サイト別代表値、根拠行等も返ります。
| 値 | 用途・注意 |
|---|---|
| product | 商品特定と日英説明。特定失敗等ではnull。confidenceが高くても人による照合を推奨 |
| market.market_usd | 市場参考値M、USD。nullは未算出。0円扱いにしない |
| U / U_strong | 米国側の比較値/eBay Sold・Amazon.com等の強い根拠 |
| J / J_landed | 日本側代表値/代行相当の費用を加えた値、いずれもUSD |
| F | 買取情報に基づく相場の下限。所有者原価・手数料を含む最終売価下限とは別 |
| condition_pricing | 自社状態との差を反映した候補。ok=falseなら未算出理由を表示 |
| fx | rateは1USDあたりJPY、sgdは1USDあたりSGD。日付・sourceも表示し、キャッシュ/代替レートの警告を隠さない |
| sources | サイト別のok / empty / error、取得件数、失敗内容。countは採用件数とは異なる |
| warnings / market.flags | 商品・成約日・取得・計算に関する注意 |
根拠行 evidence
id, source, kind, title, price, currency, shipping, shipping_included, total, total_usd, url, sold_at, origin, match, note, rank 等を保持します。自動行には exclude_reason と screen_status 等が付くことがあります。
kind: sold=成約、active=販売中、buyback=買取。match: same=同一、similar=類似、excluded=除外。同一候補を相場計算に用います。除外行も確認用に残ります。origin: auto / manual / browser。手入力APIで追加した行はmanualです。shipping_included=falseは価格と送料を合計。日本側の送料不明はWP既定750JPYを仮定する場合があり、noteに表示します。- eBayの自動取得は元WPと同じ出品価格を使用。実際の送料込み総額を保証しません。楽天は販売中価格です。
sold_atが空の自動候補は成約日未確認。メルカリの出品日時を成約日として扱いません。note内のcond:は比較先商品の状態。自社商品の状態とは分けて扱います。
根拠・商品情報の編集
GET /v1/jobs/{id}/review は処理中・失敗時にも利用可能です。
{
"job_id": "job_<ULID>", "status": "partial",
"image_count": 1, "revision": 18,
"review": {
"phase": "完了", "product": {}, "rows": [],
"traces": [], "sources": {}, "warnings": [],
"options": { "self_condition": {}, "settings": {} },
"calculation": { "market": {}, "condition": {} }
}
}省略例です。処理開始前や旧履歴ではreview=null。レビュー内の根拠は rows、公開結果では evidence という名前です。
PATCH /v1/jobs/{id}/review
最新revisionを指定します。以下は行を除外し、自社の箱・動作状態を変更する例です。
{
"revision": 18,
"updates": [{ "id": "<根拠id>", "match": "excluded", "note": "別型番のため除外" }],
"self_condition": { "box": "なし", "tested": "未確認" }
}200応答は {"code":200,"revision":19,"review":{...}}。更新後のrevisionとreviewを保持してください。
updatesは最大300件。既存行の分類・備考を変更できます。settings/self_conditionは部分更新。省略した値は維持します。productを送る場合は、GETしたproductの全フィールドを含めて編集します。カテゴリはgame / camera / audio / figure / trading_card / golf / general、箱はboxed / loose / unknown、状態区分はnew / used / unknown、ランクはgood / worn / poor。- product保存で商品を確定扱いにし、旧根拠を全件除外します。続いて
/researchで相場を再取得してください。 - queued / running / canceledは編集不可。古いrevisionは409。同時編集時は再取得して変更内容を確認します。
状態差・除外語設定
| self_conditionの項目 | 許容値 |
|---|---|
| box / manual / obi / cover | あり、なし、不明 |
| acc | 完備、一部欠品、なし、不明 |
| tested | 済、未確認、ジャンク、不明 |
| cosmetic | 良好、使用感あり、難あり、不明 |
| sealed | 未開封、開封済、不明 |
状態差調整は既定OFF。settings.cond_pricing_enabled=1 で有効にします。比較先の状態情報が足りなければ未算出です。基準価格と比較項目はcondition_pricingを参照してください。
{
"revision": 19,
"settings": { "cond_pricing_enabled": 1, "cond_extra_discount": 0 },
"self_condition": { "box": "なし", "tested": "済" }
}候補=基準USD×(1+状態差率)×(1−追加値引き率)。設定値は%単位。状態差の下限は-90%、加算上限の既定は20%です。
価格計算・状態係数の設定一覧
| settingsのキー | 既定値 | 範囲 |
|---|---|---|
| ebay_active_top_n | 5 | 整数1〜50 |
| jp_proxy_fee_pct | 12 | 0〜100% |
| jp_proxy_shipping_usd | 20 | 0〜1000 USD |
| cond_pricing_enabled | 0 | 0 / 1 |
| cond_extra_discount | 0 | 0〜90% |
| cond_bonus_cap | 20 | 0〜100% |
| cond_coef_box_missing / manual_missing / obi_missing / cover_missing | 15 / 8 / 10 / 12 | 各0〜100%。manual等にもcond_coef_を付ける |
| cond_coef_acc_missing / cond_coef_acc_partial | 10 / 5 | 各0〜100% |
| cond_coef_untested / cond_coef_junk | 20 / 50 | 各0〜100% |
| cond_coef_cosmetic_used / cond_coef_cosmetic_bad / cond_coef_sealed_diff | 10 / 20 / 30 | 各0〜100% |
除外語
market_jp_excluded_keywords / market_us_excluded_keywords に改行区切りの文字列を指定します(各最大6000文字)。既定は受領WP版の除外語で、山下さんの本番管理画面の独自設定を取得したものではありません。フィギュア等では商品自体の語が除外語に含まれることがあるため確認してください。保存後の /research で候補へ反映します。
手動根拠の追加
eBay Sold / Amazon.com / Amazon.co.jp は、ブラウザで確認した情報をUIやAPIから追記する運用です。PATCH /review の add_rows を使います。
{
"revision": 20,
"add_rows": [{
"source": "ebay", "kind": "sold", "title": "確認した商品名",
"price": 100, "currency": "USD", "shipping": 10,
"shipping_included": false,
"url": "https://www.ebay.com/itm/<確認した商品ID>",
"sold_at": "2026-09-21", "match": "same",
"note": "cond: box=あり tested=済 / 詳細を目視確認"
}]
}- sourceはebay / amazon_com / amazon_jp / mercari / yahoo_auction / rakuten / suruga_ya / shopee_sg。
- kindはsold / active / buyback。通貨はUSD / JPY / SGD。価格は正数、送料は0以上、URLはHTTPS。
- soldは実際の成約日必須。未来日・存在しない日・90日超は拒否します。上の日付は例なので、確認した実日付へ置き換えてください。
- titleは1〜200文字、noteは最大300文字。1回最大50行、全体最大500行。
- 手動行は相場の再取得でも保持します。別商品へ変更した後は適合性を再確認してください。
相場の再取得・中止
POST /v1/jobs/{id}/research
最新のreviewからrevisionを取得し、{"revision":21} を送ります。200ではなく 202、応答は {"code":202,"status":"queued"}。同じジョブIDでポーリングを再開します。
現在の商品情報で相場を再取得します。画像からの商品特定をやり直す操作ではありません。自動根拠を置換し、手動根拠を保持します。新しい写真は新規ジョブへ。商品未入力は400、処理中・中止済み・revision競合は409。
POST /v1/jobs/{id}/cancel
本文不要。queued / runningを中止します。応答はjob_id・status・completed_at。処理済みは409です。外部APIへ送信済みのリクエストや、その処理料金を取り消すものではありません。
一覧・画像
GET /v1/jobs
クエリ: limit(既定20、最大100)、cursor、status、external_user_id。新しい順に返します。
{
"jobs": [{
"job_id": "job_<ULID>", "status": "partial",
"title": "商品名", "external_user_id": "your-user-id",
"created_at": "2026-09-21T00:00:00.000Z",
"completed_at": "2026-09-21T00:02:00.000Z",
"error_text": null,
"image_url": "/v1/jobs/job_<ULID>/image",
"image_count": 1, "image_available": true
}],
"next_cursor": null
}next_cursorがあれば次のリクエストのcursorへ渡します。文字列はURLエンコードし、内容を自分で組み立てません。
GET /v1/jobs/{id}/image?i=0
iは0始まり、省略時0。画像バイナリを返します。認証が必要なので、ブラウザ表示は認証付きfetch → Blob URL等を使います。画像の既定保持期間は7日、保持期限後や存在しない番号は404。古い履歴が残っていても画像が取得できるとは限りません。
ヘルス・対応機能
/v1/healthz:{"status":"ok","api_version":"2.0.1"}。プロセス生存のみで、DB・worker・外部APIの正常性を保証しません。/v1/readyz: 認証必須。DB・Redis・workerが利用可能なら200、未準備なら503。外部プロバイダの疎通は含みません。/v1/capabilities: 認証必須。api_version、schema_version、engine_version、model、automatic_sources、manual_sources、max_images、image_retention_days、webhooksを返します。現在webhooks=false。
自動取得はeBay・ヤフオク・メルカリ・楽天・駿河屋。販売中・成約・買取の違いや、0件と取得失敗を表示で区別してください。
エラー・制限
多くのエラーは {"error":"説明"}。入力検証ではissues、状態競合ではstatus等が付く場合があります。文言の完全一致に依存せず、HTTPステータスと必要なフィールドで分岐してください。
| HTTP | 主な原因 | 対処 |
|---|---|---|
| 400 | 入力値、cursor、非対応のURL画像/callback、手動成約日等 | 入力を修正。無条件再送しない |
| 401 | キーなし・無効 | 設定確認。キーを画面やログへ出さない |
| 404 | 不存在/他キーのジョブ/画像保持期限 | 所有権・ID・保持期限を確認 |
| 409 | 結果未完了、処理中編集、古いrevision等 | 状態・reviewを再取得 |
| 413 / 415 | サイズ制限/未対応画像形式 | 画像サイズと形式を修正 |
| 429 | レート制限 | Retry-Afterがあれば従い、取得間隔を延ばす |
| 500 / 503 | 内部障害/準備未完了 | 既存ジョブの状態を確認。POST再送による重複に注意 |
外部サイトの403等はジョブ全体のHTTP403として返るとは限りません。結果の sources.{site}.status=error と説明を確認してください。
同じ画像・同じ入力でもライブ価格・取得候補・AI判定は変わります。価格の完全一致ではなく、商品特定・採用根拠・計算経路を確認してください。
連携時の確認項目
- キーはサーバー側だけに置き、external_user_idとログインユーザーの権限を照合する。
- 202後はjob_idを保存し、ポーリングは4〜5秒間隔。通信切断後は保存済みIDから再開する。
- partialとnull価格を正しく扱い、警告・サイト失敗・根拠の同一/類似/除外を表示する。
- 編集では最新revisionを使用し、409時に上書きしない。
- 商品変更後は相場の再取得、画像変更時は新規ジョブにする。
- 相場M・状態調整候補・最終出品価格を区別する。