本文へスキップ

その他

言語と通貨

Qualit.ly API

Weidian、Taobao、1688 の商品データ、QC 画像、メタデータ。Bearer トークン認証、寛大なレート制限、段階的なプラン。

API キーを取得クイックスタート

はじめに

すべてのリクエストは https://backend.qualit.ly/api/v1 に送信します。3 つのステップ:

  1. 1

    キーを取得

    サインインして、開発者ダッシュボードから API キーを作成します。

  2. 2

    リクエストを送信

    キーを Bearer トークンとして Authorization ヘッダーに含めて送信します。

  3. 3

    データを取得

    商品データと QC 画像を含む JSON レスポンスを受け取ります。

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

認証

有効な API キーを Authorization ヘッダーに Bearer スキームで含めます。

http
Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

キーの形式

キーは qc_{mode}_{random} の形式です。mode は live または test、random は暗号学的にランダムな 32 文字です。

キーは作成時に一度だけ表示されます。保存するのは SHA-256 ハッシュのみのため、紛失したキーは復元できません — 失効して新しく作成してください。

IP 許可リスト

開発者ダッシュボードから、キーを特定の IP または CIDR 範囲に制限できます（任意）。許可リスト外の IP からのリクエストには 403 が返されます。許可リストが空の場合、すべての IP が許可されます。

レート制限

2 つのバケットがあります: 毎分と毎月。段階はリクエストごとにアカウントから判定されるため、アップグレードは即座に反映されます。また、制限はあなたのすべてのキーに共通で適用されます。

段階/ 分/ 月
Basic301,000
Early Adopter403,000
Pro30025,000
Pro+1,000500,000
カスタム無制限無制限

/me と /usage は認証は必要ですが計測対象外です: 自分の状況を確認しても、そのクォータ自体は消費されません。

ヘッダー

拒否されたレスポンスだけでなく、すべてのレスポンスに付与されます。

X-RateLimit-Limitあなたの段階で毎分許可されるリクエスト数、または「unlimited」。
X-RateLimit-Remaining現在の 1 分間に残っているリクエスト数。
X-RateLimit-Resetあなたをブロックしたカウンターがリセットされるまでの秒数。

レート制限に達したとき

API は 429 を返します — 毎分のバーストには RATE_LIMITED、毎月のクォータには QUOTA_EXCEEDED — 待機すべき秒数は retry_after に入っています。

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-minute rate limit exceeded",
    "retry_after": 37
  }
}

エラー

エラーは 2xx 以外のステータスと、トップレベルの error オブジェクトを、安定した code と message 付きで返します。判定には message ではなく code を使ってください — message は変更されることがあります。

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
400BAD_REQUESTリクエストの本文またはパラメーターが無効です。
401INVALID_KEYAPI キーがない、形式が不正、または不明です。
401REVOKED_KEYAPI キーはダッシュボードで無効化されています。
403IP_NOT_AUTHORIZEDリクエストの IP がキーの許可リストにありません。
403FORBIDDENお使いの段階ではこのエンドポイントにアクセスできません。
404NOT_FOUND要求されたリソースが存在しません。
429RATE_LIMITED毎分の制限を超過しました。
429QUOTA_EXCEEDED月間クォータを使い切りました。UTC の月替わりにリセットされます。
500INTERNALこちらの問題です。バックオフしながら再試行しても問題ありません。

エンドポイント

以下のパスはすべて https://backend.qualit.ly/api/v1 からの相対パスです。ストアは weidian、taobao、1688 です。チップが付いていないエンドポイントはすべてのプランで利用できます。

商品取得

GET/products/{storefront}/{listing_id}

ストアと ID で単一の商品を取得します。メタデータと最大 5 枚の QC プレビューサムネイルを返します。ほとんどの連携がまずこのエンドポイントから始めます。

storefront必須string次のいずれか: weidian、taobao、1688
listing_id必須stringストアの商品出品 ID。

例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

レスポンス

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
    "pic_gif": null,
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "qc_preview": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg"
    ]
  }
}

商品検索

GET/products/search

商品名でカタログを検索します — 商品 URL も照合対象です。ページネーションはなく、各プランは決まった件数までの結果を返します。

q必須string検索テキスト。複数の単語は商品名と商品 URL に対して AND 条件で照合されます。
storefrontstringweidian、taobao、1688 のいずれかに絞り込みます。
has_qcbooleanQC 写真がある商品のみを対象にします。
limitintegerプランの上限より少ない件数を指定できます。上限を超える値は上限に切り下げられ、超過方向には調整されません。

ページネーションはありません。各プランは 1 回の検索につき決まった件数までの結果を返します。limit で件数を減らすことはできますが、増やすことはできません。

プラン最大件数
Basic5
Early Adopter10
Pro50
Pro+100
カスタム250

例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/products/search?q=jordan+1&storefront=weidian&has_qc=true&limit=10"

レスポンス

json
{
  "query": "jordan 1",
  "count": 10,
  "limit": 10,
  "max_results": 100,
  "data": [
    {
      "id": 482910,
      "storefront": "weidian",
      "listing_id": "7231368393",
      "name": "AJ1 Retro High OG",
      "price": "¥470.00",
      "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
      "product_url": "https://weidian.com/item.html?itemID=7231368393",
      "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
      "qc_count": 12,
      "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
    }
  ]
}

フィールド

max_resultsプランの上限 — `limit` はこの値に切り下げられます。
countこのレスポンスに実際に含まれる件数。

商品の一括取得

Pro+
POST/products/batch

1 回の呼び出しで最大 100 件の商品をまとめて取得します。各項目は独立して処理されるため、商品が見つからなくてもバッチ全体は失敗せず、同じ位置にエラーとして返ります。

items必須array{ storefront, listing_id } オブジェクトの配列。上限は 100 件、ただしプランの 1 ページあたりの上限がそれより低い場合はそちらが適用されます。

リクエストボディ

json
{
  "items": [
    { "storefront": "weidian", "listing_id": "7231368393" },
    { "storefront": "taobao", "listing_id": "123456789" }
  ]
}

例

bash
curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"storefront":"weidian","listing_id":"7231368393"}]}' \
  https://backend.qualit.ly/api/v1/products/batch

レスポンス

json
{
  "results": [
    {
      "data": {
        "id": 482910,
        "storefront": "weidian",
        "listing_id": "7231368393",
        "name": "AJ1 Retro High OG",
        "price": "¥470.00",
        "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
        "qc_count": 12,
        "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
      }
    },
    { "error": { "code": "NOT_FOUND" } }
  ]
}

ランダム商品

POST/products/random

QC 写真がある商品をランダムに 1 件取得します。ショーケースやフィード、カタログのサンプリングに便利です。リクエストボディは不要です。

例

bash
curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/random

レスポンス

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
  }
}

QC メタデータ

GET/qc/{storefront}/{listing_id}

商品の QC 写真枚数と、最初の 3 枚のサムネイルを返します — 画像リスト全体を取得せずに済みます。

storefront必須string次のいずれか: weidian、taobao、1688
listing_id必須stringストアの商品出品 ID。

例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/weidian/7231368393

レスポンス

json
{
  "data": {
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "thumbnails": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg",
      "https://cdn.qualit.ly/qc/0f19ab77.jpg"
    ]
  }
}

QC 画像

Pro+
GET/qc/{id}/images

商品のインデックス済み QC 写真をすべて返します。数値の商品 ID を指定するか、対応する商品リンクを ?url= で渡して API に解決させることもできます。

id必須integer数値の商品 ID。?url= で検索する場合は 0 を指定します。
urlstringID の代わりに解決させる完全な商品 URL。指定されている場合はこちらが優先されます。

商品 ID で

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/482910/images

URL で

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/qc/0/images?url=https://weidian.com/item.html?itemID=7231368393"

レスポンス

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "images": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg"
    ]
  }
}

?url= パラメーターは、Weidian、Taobao、1688、およびリンクコンバーターが対応するすべてのエージェントの商品リンクを受け付けます。画像は常に CDN の URL です。

アカウント情報

GET/me

アカウント情報、リクエストに使用したキー、そのキーが解決される段階を返します。ヘルスチェックにも便利です。

例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/me

レスポンス

json
{
  "user": { "id": 12345, "username": "you" },
  "key": { "id": 7, "mode": "live" },
  "tier": "pro_plus"
}

使用状況

GET/usage

毎分・毎月両方のレート制限バケットにおける現在位置を、リセット時刻とともに返します。/me と同様、このエンドポイントは認証は必要ですが計測対象外です — クォータについて尋ねても、そのクォータは消費されません。

例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/usage

レスポンス

json
{
  "tier": "pro_plus",
  "key": { "id": 7, "mode": "live" },
  "minute": {
    "limit": 1000,
    "used": 12,
    "remaining": 988,
    "reset_in_seconds": 37,
    "reset_at": "2026-08-20T18:42:00.000Z"
  },
  "month": {
    "limit": 500000,
    "used": 1843,
    "remaining": 498157,
    "reset_in_seconds": 1159200,
    "reset_at": "2026-09-01T00:00:00.000Z",
    "bucket": 202608
  }
}

フィールド

tier次のいずれか: basic、early_adopter、pro、pro_plus、custom
limit / remainingCustom 段階では null（無制限）。
used現在のウィンドウでカウントされたリクエスト数。毎分カウンターは 60 秒ごと、毎月カウンターは UTC の月替わりにリセットされます。
reset_atISO 8601、UTC。
bucket毎月カウンター用の内部 YYYYMM キー。

コードサンプル

bash
curl -H "Authorization: Bearer $QUALITLY_KEY" \
  "https://backend.qualit.ly/api/v1/products/search?q=jordan+1&storefront=weidian"

MCP サーバー

同じ API が、ホスト型の Model Context Protocol（MCP）サーバーとしても提供されているので、Claude、Cursor、VS Code など、任意の MCP クライアントから HTTP を書かずに商品や QC セットを照会できます。API キー、レート制限、段階のルールはそのまま引き継がれます。

サーバー URL

https://backend.qualit.ly/api/mcp

トランスポート

StreamableHTTP (POST)

認証

Authorization: Bearer qc_live_…

ツール

登録されるのは、あなたの段階で呼び出せるツールだけです。そのため Basic のキーには、拒否されるはずのツールは表示されません。

get_productストアと商品 ID で商品を検索
search_products名前で検索。ストアや QC の有無でフィルタリング可能
get_products_batch1 回の呼び出しで最大 100 件の商品を検索Pro+
random_productQC写真がある商品をランダムに1件取得
get_qcQC 件数と 3 枚のサムネイル URL
get_qc_images完全な CDN 画像リスト（ID または URL で）Pro+
get_me現在のキー、ユーザー、段階
get_usage毎分・毎月のクォータ状況

Claude Desktop、Cursor、VS Code

claude_desktop_config.json（Claude → 設定 → 開発者）か、エディタの MCP 設定に、このサーバーを追加します。

Claude Desktop

json
{
  "mcpServers": {
    "qualitly": {
      "url": "https://backend.qualit.ly/api/mcp",
      "headers": {
        "Authorization": "Bearer qc_live_YOUR_KEY"
      }
    }
  }
}

Cursor / VS Code

json
{
  "mcp": {
    "servers": {
      "qualitly": {
        "url": "https://backend.qualit.ly/api/mcp",
        "headers": {
          "Authorization": "Bearer qc_live_YOUR_KEY"
        }
      }
    }
  }
}

OAuth ディスカバリーに対応したクライアント — Claude.ai や ChatGPT など — は、ハードコードしたキーをまったく使わずに済みます。未認証のリクエストには、サーバーの OAuth メタデータを指す WWW-Authenticate ヘッダーが返り、クライアントはそれを使ってユーザーをログインページへ誘導します。

動作確認

bash
# List the tools your key can see
curl -X POST https://backend.qualit.ly/api/mcp \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

プランと段階

段階はリクエストごとにアカウントから判定されるため、アップグレードは次の呼び出しから即座に反映されます — 新しいキーは不要です。Basic より上の段階が必要なのは、バッチ検索・フル QC 画像リスト・?url= 抽出だけで、それ以外はすべて利用量の違いにすぎません。

プラン/ 分/ 月検索結果バッチ + 画像
Basic301,0005
Early Adopterレガシー403,00010
Pro30025,00050
Pro+1,000500,000100
カスタム無制限無制限250

Early Adopter はレガシープランです — 既存アカウントのみが保有しており、新規販売はしていません。Pro+ 以上が必要な場合は、[email protected] が Custom の上限を設定します。

プラン・料金・特典の詳細を見る
検索

Cookie

ログイン状態と保存した商品を保持するために使用します。分析は同意した場合のみです。