{
  "lang": "ja",
  "ページ": "https://x402-catalog-history.ai-business-surface.workers.dev/ja/url-to-markdown",
  "title": "url to markdown api の実測 — 0.01 USDC の /markdown を払う前に分かること",
  "h1": "url to markdown api を買う前に読む — 0.01 USDC・402 の前に URL を無料で検査できる",
  "description": "url to markdown api は 1 URL 0.01 USDC。2026-10-19 に支払いなしで測ると、有効な URL でも url なしでも同じ 16,712 B の 402 が返り、応答は中央値 409 ms / 193 ms / 172 ms でした。一方、壊れた URL・内部アドレス・非対応ポートは支払い前に 400（269〜351 B・中央値 139〜157 ms）で無料で弾かれます。402 から読める価格・制限（2048文字・5秒・3リダイレクト・512 KiB）と、200 の本文を取っていない未確認部分を分けて書きます。",
  "検索語": "url to markdown api",
  "読者の問い": "記事の URL を渡すだけで Markdown が返る API は、何をどこまでやってくれて、いくらで、どこで失敗するのか。",
  "実測日": "2026-10-19 JST",
  "実測": {
    "caption": "url to markdown api（/markdown）の実測（2026-10-19 JST・公開URLへの支払いなしGET・各3回）",
    "columns": [
      "リクエスト",
      "応答",
      "大きさ",
      "応答時間（3回）",
      "中身"
    ],
    "rows": [
      [
        "/markdown?url=<Wikipedia HTTP 402>",
        "402",
        "16,712 B",
        "816 / 409 / 180 ms",
        "0.01 USDC の宣言のみ。200 の本文は未取得"
      ],
      [
        "/markdown?url=<自サイトの /ja 記事>",
        "402",
        "16,712 B",
        "212 / 188 / 193 ms",
        "対象が 200 を返すページでも同じ 402"
      ],
      [
        "/markdown（url なし）",
        "402",
        "16,712 B",
        "223 / 172 / 157 ms",
        "パラメータ検証より前に課金ゲート"
      ],
      [
        "/markdown?url=http://127.0.0.1/",
        "400",
        "351 B",
        "162 / 157 / 139 ms",
        "blocked_target（loopback_address）。取得なし・無料"
      ],
      [
        "/markdown?url=https://example.com:22/",
        "400",
        "269 B",
        "158 / 131 / 139 ms",
        "blocked_port。許可ポートの一覧を返す"
      ],
      [
        "/markdown?url=not-a-url",
        "400",
        "271 B",
        "162 / 141 / 134 ms",
        "invalid_url。取得なし・無料"
      ],
      [
        "同じ 402 の accepts[0] を3回ハッシュ",
        "—",
        "—",
        "—",
        "sha256 = 782bbb192518f473… で一致"
      ]
    ],
    "note": "402 の accepts[0] は scheme=exact、network=base、maxAmountRequired=10000（USDC 6桁で 0.01）、maxTimeoutSeconds=60。400 は「Nothing was fetched and no payment is requested」と明記され、課金ゲートより前に返ります。応答時間の中央値は有効URL 409 ms（初回 816 ms を含む）、自サイト 193 ms、url なし 172 ms、400 は 139〜157 ms。"
  },
  "見出し": [
    "結論",
    "実測",
    "402 から読める仕様",
    "払う前に無料でできること",
    "失敗したときの返り方",
    "自分でやるか、0.01 を払うか",
    "次の一歩"
  ],
  "本文": [
    {
      "見出し": "結論",
      "html": "<p><code>/markdown</code> は、渡した URL を1回だけ取得し、本文を <code>text/markdown</code> として返す <strong>1回 0.01 USDC</strong> の API です。ネットワークは Base、資産は USDC、支払いは <code>exact</code>、タイムアウトは 60 秒。買い方は「402 を見る → 同じリクエストに <code>PAYMENT-SIGNATURE</code> を付けて 200 を受ける」の2回です。</p><p>この記事の実測で買い手に効くのは2点です。第一に、<strong>有効な URL でも url なしでも同じ 16,712 B の 402</strong> が返ります。つまり 402 の段階では「この URL が変換できるか」も「変換の質」も分かりません。第二に、<strong>壊れた URL・内部アドレス・非対応ポートは支払い前に 400 で無料で弾かれます</strong>（269〜351 B・139〜157 ms）。<strong>形式の検査は無料、中身の品質は有料</strong>という切り分けです。</p><p>2026-10-18T16:25Z の facilitator の <code>listing-status</code> は <code>listed=true</code>、<code>lastProbe.status=alive</code>、<code>httpStatus=402</code>。カタログからは届きます。ただし<strong>200 の本文は支払っていないので未取得</strong>で、抽出の精度・保持される要素・失敗時の本文は、この記事では確認していません。</p>"
    },
    {
      "見出し": "実測",
      "html": "<table>\n<thead><tr><th>リクエスト</th><th>応答</th><th>大きさ</th><th>応答時間（3回）</th><th>中身</th></tr></thead>\n<tbody>\n<tr><td><code>/markdown?url=&lt;Wikipedia HTTP 402&gt;</code></td><td>402</td><td>16,712 B</td><td>816 / 409 / 180 ms</td><td>0.01 USDC の宣言のみ。200 の本文は未取得</td></tr>\n<tr><td><code>/markdown?url=&lt;自サイトの /ja 記事&gt;</code></td><td>402</td><td>16,712 B</td><td>212 / 188 / 193 ms</td><td>対象が 200 を返すページでも同じ 402</td></tr>\n<tr><td><code>/markdown</code>（url なし）</td><td>402</td><td>16,712 B</td><td>223 / 172 / 157 ms</td><td>パラメータ検証より前に課金ゲート</td></tr>\n<tr><td><code>/markdown?url=http://127.0.0.1/</code></td><td>400</td><td>351 B</td><td>162 / 157 / 139 ms</td><td><code>blocked_target</code>（loopback_address）。取得なし・無料</td></tr>\n<tr><td><code>/markdown?url=https://example.com:22/</code></td><td>400</td><td>269 B</td><td>158 / 131 / 139 ms</td><td><code>blocked_port</code>。許可ポートの一覧を返す</td></tr>\n<tr><td><code>/markdown?url=not-a-url</code></td><td>400</td><td>271 B</td><td>162 / 141 / 134 ms</td><td><code>invalid_url</code>。取得なし・無料</td></tr>\n<tr><td>同じ 402 の <code>accepts[0]</code> を3回ハッシュ</td><td>—</td><td>—</td><td>—</td><td>sha256 = <code>782bbb192518f473…</code> で一致</td></tr>\n</tbody>\n</table>\n<p>最初の 816 ms は初回（コールド）で、2回目以降は 180〜409 ms でした。同じ URL への再取得はサービス側の 60 秒キャッシュに当たる設計なので、<strong>連続で叩いても毎回ページを取りに行くとは限りません</strong>（キャッシュの実動作は未確認）。402 の 16,712 B は、価格・受取先・利用規約・bazaar の入出力例まで含むためです。400 の 269〜351 B と比べると<strong>約48〜62倍</strong>あります。</p><p><code>accepts[0]</code> の指紋は3回とも同じでした。価格と受取先が呼び出しごとに変わっていないことを、支払い前に無料で確かめられます。</p>"
    },
    {
      "見出し": "402 から読める仕様",
      "html": "<ul>\n<li><strong>価格</strong>：<code>maxAmountRequired=10000</code>（0.01 USDC）、<code>scheme=exact</code>、<code>network=base</code>、<code>maxTimeoutSeconds=60</code>。<code>price</code> も <code>amount_usd: 0.01</code> と一致していました。</li>\n<li><strong>出力</strong>：<code>text/markdown; charset=utf-8</code>。JSON のラッパーなしで、Markdown そのものが返る宣言です。見出し・段落・リスト・コードブロック・リンク・画像・引用・表を残し、ナビ・Cookie バナー・広告・サイドバー・共有ボタン・フッタを落とすと書いています。</li>\n<li><strong>付随ヘッダ（宣言）</strong>：<code>x-markdown-target</code>（リダイレクト後の URL）、<code>x-markdown-title</code>、<code>x-markdown-words</code>、<code>x-markdown-source-bytes</code>、<code>x-markdown-cache</code>（hit/miss）、<code>x-markdown-http-status</code>、<code>x-markdown-container</code>。</li>\n<li><strong>入力の制限（実装）</strong>：URL は 2048 文字まで。ポートは 80 / 443 / 3000 / 8000 / 8080 / 8443 のみ。ユーザー名・パスワード埋め込みは拒否。ループバック・プライベート・リンクライト・内部・単一ラベルは拒否。</li>\n<li><strong>取得の制限（実装）</strong>：1回の GET、5 秒で打ち切り、リダイレクトは 3 回まで、本文は 512 KiB まで。HTML / XHTML / XML / text/plain / text/markdown だけを変換し、それ以外は <code>not_markdown_source</code>。</li>\n<li><strong>失敗の型（宣言）</strong>：取得不能は 502 で <code>target_timeout</code> / <code>unreachable</code>、本文が分離できないと <code>no_article_body</code>（Markdown が 40 文字未満）。200 でも 502 でも <code>delivery.payment</code> に取引と支払者が入り、オンチェーンと照合できるとしています。</li>\n</ul>\n<p>ここで注意すべきは、<strong>402 に無料プレビューが無い</strong>ことです。本文の <code>try_before_you_pay</code> は <code>null</code> でした。bazaar の <code>output.example</code> は「こういう形で返る」という固定の例で、<strong>自分の URL を変換した結果ではありません</strong>。抽出の質は、0.01 を払って 200 を受けるまで分かりません。</p>"
    },
    {
      "見出し": "払う前に無料でできること",
      "html": "<p>形式の検査は課金の前に済みます。実際、<code>http://127.0.0.1/</code> は 351 B・中央値 157 ms で <code>blocked_target</code>、<code>https://example.com:22/</code> は 269 B・139 ms で <code>blocked_port</code>、<code>not-a-url</code> は 271 B・141 ms で <code>invalid_url</code> を返し、いずれも「取得していない・支払いも要求していない」と明記されました。<strong>この 400 には費用も課金も発生しません</strong>。</p><pre><code>curl -s -o /dev/null -w '%{http_code} %{size_download} %{time_total}\\n' \\\n  \"https://x402-catalog-history.ai-business-surface.workers.dev/markdown?url=https%3A%2F%2Fexample.com%2Farticle\"</code></pre>\n<p>200 が返れば URL は受け付けられる形です（この時点ではまだ 402 で、本文は返りません）。400 なら、その URL は<strong>払っても変換されない</strong>ので、課金前に別の手段へ切り替えられます。あわせて 402 の <code>accepts[0]</code> を保存しておけば、価格・受取先・ネットワークの変化も検出できます。3回測った指紋は <code>782bbb192518f473…</code> で一致しました。</p><p>ただし<strong>中身の検査はできません</strong>。対象が 200 を返すページかどうか、本文が 40 文字以上あるか、抽出が崩れないかは、支払った後の結果でしか分かりません。これは「安いから試す」で埋めるしかない部分です。</p>"
    },
    {
      "見出し": "失敗したときの返り方",
      "html": "<p>宣言では、失敗は 400（形式・ポリシー違反、課金前）、429（レート制限、課金前）、502（取得後の変換失敗、課金後）に分かれます。レート制限は同一クライアント 6 回/分、全体 120 回/分で、<strong>402 を返す前</strong>に 429 になります。連打して「402 を何度も確認する」使い方は、この枠を消費します。</p><p>502 のときも支払いは確定済みで、<code>delivery.payment</code> に取引ハッシュと支払者が入ります。402 の <code>terms.refund</code> は「オンチェーンで決済され、自動返金はしない」と明記しています。<strong>失敗しても 0.01 は戻らない</strong>前提で、1回ごとの少額購入に向く設計です。まとめ買いや一括変換の割引はありません。</p><p>この記事では 502 も 200 も実際には取っていません。したがって<strong>「失敗時も本当に 502 と delivery が返るか」「40 文字判定が期待通りか」は未確認</strong>です。宣言と実装を読んだ範囲の記述であることを明記します。</p>"
    },
    {
      "見出し": "自分でやるか、0.01 を払うか",
      "html": "<ul>\n<li><strong>自分でやる（無料）</strong>：1日数本なら、Readability 系のライブラリと HTML→Markdown の変換を自分の環境に置く方が安い。取得・タイムアウト・リダイレクト・除外要素の調整も自分でできる。初期費用は時間だけ。</li>\n<li><strong>/markdown に払う（0.01/回）</strong>：変換だけを外に出したい、取得元の制限（内部アドレス拒否・512 KiB・5秒）を自前で書きたくない、結果をそのままプロンプトやファイルに貼りたい。1回ごとの課金で、アカウントもキーも要らない。</li>\n<li><strong>向かない場合</strong>：変換の質を買う前に確かめたい、PDF や画像を扱いたい、大量に一括変換したい、失敗時の返金を保証してほしい。この3つは宣言からも実測からも満たされていません。</li>\n</ul>\n<p>判断の材料は「形式検査が無料で済む」ことと「品質は有料でしか分からない」ことの非対称です。URL が正しい形かどうかは無料で確かめ、品質は 0.01 を1回払って確かめる、という順番になります。</p>"
    },
    {
      "見出し": "次の一歩",
      "html": "<p>相手の端点を払う前に確かめる手順は <a href=\"https://x402-catalog-history.ai-business-surface.workers.dev/ja/check-before-paying\"><code>/ja/check-before-paying</code></a>、価格の相場は <a href=\"https://x402-catalog-history.ai-business-surface.workers.dev/ja/price-benchmark\"><code>/ja/price-benchmark</code></a> に実測でまとめています。カタログ掲載の確認は facilitator の <code>/discovery/listing-status?resource=…/markdown</code> で無料で読めます（今回は <code>listed=true</code>・<code>alive</code>・<code>402</code>）。</p>"
    }
  ],
  "一覧": "https://x402-catalog-history.ai-business-surface.workers.dev/ja"
}