Hyperouter API

バージョン v1 · 2026 年 10 月 25 日更新

Hyperouter は、多数のモデルベンダーの手前に置かれた 1 つの HTTP API です。モデルを指定したリクエストを送ると、Hyperouter がそのモデルを提供できるプロバイダーを選び、リクエストを転送して、そのプロバイダーの定価で残高から課金します。

すべてのエンドポイントは、OpenAI のリクエストとレスポンスの形式に従っています。ベース URL と API キーを変更すれば、OpenAI SDK がそのまま動作します。Hyperouter は OpenAI のボディにいくつかのフィールドを追加しており、このリファレンスでは追加分であることを明記しています。

クイックスタート

1. サインインして API キーを作成します。キーは sk-hr-v1- で始まり、一度だけ表示されます。
2. 環境変数（たとえば HYPEROUTER_API_KEY）に保存します。
3. クレジットを追加します。ダッシュボードでチャージの依頼を作成してください。お支払いの確認後、スタッフが残高に反映します。
4. 任意の OpenAI SDK の接続先を上記のベース URL に向け、モデルを選びます。

curl https://api.hyperouter.app/v1/chat/completions \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hyperouter.app/v1",
  apiKey: process.env.HYPEROUTER_API_KEY,
});

const res = await client.chat.completions.create({
  model: "x-ai/grok-4.7",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hyperouter.app/v1",
    api_key=os.environ["HYPEROUTER_API_KEY"],
)

res = client.chat.completions.create(
    model="x-ai/grok-4.7",
    messages=[{"role": "user", "content": "Hello"}],
)
print(res.choices[0].message.content)

認証

すべてのリクエストで、API キーをベアラートークンとして送信します。

Authorization: Bearer sk-hr-v1-...

キーは残高へのアクセス権を持ちます。サーバー側で管理し、ブラウザーやモバイルのコードには決して含めないでください。Hyperouter が保存するのは各キーのハッシュのみのため、紛失したキーを再表示することはできません。新しいキーを作成してください。

ダッシュボードでは、キーに名前を付けたり、クレジット上限を設定したり、無効にしたりできます。無効にしたキーは直ちに使えなくなります。キーの上限を超えることになるリクエストは、402 insufficient_credits で拒否されます。

認証エラー

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

{ "error": { "message": "The API key is not valid.", "type": "authentication_error", "code": "invalid_api_key", "param": null } }

エラー

すべてのエラーは、OpenAI のエラーオブジェクトと、対応する HTTP ステータスで返されます。

{
  "error": {
    "message": "n must be an integer from 1 to 128",
    "type": "invalid_request_error",
    "code": "invalid_body",
    "param": "n"
  }
}

type とステータス

Hyperouter は 502 や 504 を返しません。これらは、エラーボディのない、エッジネットワークからの素のページとして届いてしまうためです。ゲートウェイであればこれらを返す場面では、下記のボディを持つ 503 が返り、ゲートウェイのステータスは X-Upstream-Status に入ります。

返される可能性のある code

リトライと冪等性

ネットワークエラーやタイムアウトからは、Hyperouter がリクエストを受信したかどうかはわかりません。再送すると、2 つ目のジョブが開始され、二重に支払うことになりかねません。Idempotency-Key を使うと、再送を安全に行えます。Hyperouter は再送を識別し、2 つ目のジョブを開始せず、2 回目のクレジット確保も行わずに、最初のリクエストの結果で応答します。

お金のかかるリクエストには、毎回キーを送信してください。新しいリクエストごとに、UUID v4 などのランダムな値を新たに生成します。その値をリクエストとともに保持し、同じリクエストを再送するときは毎回同じ値を送信します。

キーの送信

このヘッダーは、次のエンドポイントで受け付けられます。

OpenAI SDK は、このヘッダーを自動では送信しません。追加ヘッダーとして渡してください。SDK は、自動リトライの際にもそのヘッダーを変更せずに再送します。

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "A lighthouse at dusk", "n": 1}'

import uuid

key = str(uuid.uuid4())  # one per request; reuse it when you retry this request
img = client.images.generate(
    model="x-ai/grok-imagine-image",
    prompt="A lighthouse at dusk",
    extra_headers={"Idempotency-Key": key},
)

import { randomUUID } from "node:crypto";

const key = randomUUID(); // one per request; reuse it when you retry this request
const img = await client.images.generate(
  { model: "x-ai/grok-imagine-image", prompt: "A lighthouse at dusk" },
  { headers: { "Idempotency-Key": key } },
);

再送で返されるもの

ルール

• スコープ。キーは、それを送信した API キーに属します。2 つの API キーが同じ値を使っても、互いに影響しません。
• 有効期間。キーは、最初のリクエストから 30 分間有効です。その間に再試行してください。
• 同一のリクエスト。メソッド、パス、ボディが一致する場合、2 つのリクエストは同一とみなされます。JSON は解析後に比較されるため、フィールドの順序や空白は影響しません。画像や動画はボディ内の URL なので、比較されるのは URL であり、その先のバイト列は比較されません。
• 課金。キーを付けたリクエストは、再送の回数にかかわらず、最大で 1 回だけ課金されます。最初のリクエストの結果で応答した再送は、無料です。
• 保証。1 つのキーで開始されるジョブは 1 つまでです。2 つの再送が同時に届いた場合も同様です。

チャット補完

チャットの応答は再現されません。同じキーでの再送には、コード idempotency_key_replayed の 409 が返り、error.generation_id が最初のリクエストの ID になります。リクエストが再実行されたり、再度課金されたりすることはありません。ステータス、利用量、費用は、GET /v1/generations/{id} で最初のリクエストを照会して確認してください。最初のチャット補完が失敗し、課金されなかった場合は、そのキーは解放され、再送は新規リクエストとして実行されます。

{
  "error": {
    "message": "A request with this Idempotency-Key already ran as generation 019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17. Chat replies are not replayed: GET /v1/generations/019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17 for its record.",
    "type": "conflict",
    "code": "idempotency_key_replayed",
    "param": null,
    "generation_id": "019a1f3c-5b7e-7d21-9c4a-2e8f6b0d3a17"
  }
}

OpenAI SDK の自動リトライ

OpenAI SDK は、408、409、429、または 5xx の応答を、既定で 2 回再試行します。ただし、応答にレスポンスヘッダー x-should-retry: false が付いている場合は再試行しません。Hyperouter は、再試行すると 2 つ目のジョブや 2 回目の課金が発生するすべての応答に x-should-retry: false を付けて送信します。

• 同期画像の 503 timeout。そのジョブは継続し、成功した時点で課金されます。generation_id を使って GET /v1/generations/{id} をポーリングしてください。
• ジョブの作成後の 500。たとえば、完成した画像を読み戻せない場合です。
• 409 idempotency_key_reused と idempotency_key_replayed。再試行しても結果は変わりません。

429 と 409 idempotency_key_in_use、およびジョブが存在する前の 5xx には、このヘッダーを付けません。これらは再試行しても安全です。Idempotency-Key を付けていれば、どの再試行も安全です。

モデル

アカウントが現在呼び出せるすべてのモデルを、価格と対応機能とともに一覧表示します。有効なプロバイダーがないモデルは表示されません。一部のモデルは、アカウントへのアクセス許可が必要で、許可されると一覧に表示されます。このエンドポイントには API キーが必要で、そのキーのアカウントが呼び出せるモデルを一覧表示します。応答は、お客様のクライアント側のみで 60 秒間キャッシュできます。

パラメーター

なし。

レスポンス

{
  "data": [{
    "id": "x-ai/grok-4.7",
    "name": "Grok 4.7",
    "kind": "chat",
    "context_length": 500000,
    "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["text"] },
    "pricing": {
      "prompt": "0.000002", "completion": "0.000006", "input_cache_read": "0.0000005",
      "request": "0", "image": "0", "video_second": "0"
    },
    "top_provider": { "context_length": 500000, "max_completion_tokens": 32768 },
    "response_modes": ["sync", "stream"],
    "supported_parameters": ["max_tokens", "temperature", "top_p", "stop", "stream", "tools", "tool_choice", "response_format", "seed", "frequency_penalty", "presence_penalty"],
    "extra_parameters": {}
  }]
}

curl https://api.hyperouter.app/v1/models \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

エラー

このエンドポイント固有のエラーはありません。

チャットモデル

100 万トークンあたりの価格：入力 / キャッシュされた入力 / 出力。

x-ai/ のモデルでは、プロンプトが 200,000 トークン以上のリクエストは、全体が長コンテキスト料金で課金されます。この料金は上記の 2 倍です。deepseek/ のモデルは、プロンプトの長さにかかわらず料金が一定で、既定では回答の前に推論を行い（reasoning_effort: "none" で無効にできます）、その推論分も max_tokens に数えられ、上限は 384,000 です。z-ai/glm-5.3 は常に推論します。reasoning_effort は low、high、max のいずれかで、none は拒否されます。openai/ のモデルも推論を行い、プロンプトは最大 272,000 トークンです。

チャット補完

会話に対するモデルの応答を作成します。ボディは OpenAI の Chat Completions リクエストです。Hyperouter は models、provider、moderation を追加しています。

パラメーター

その他のフィールドは無視されます。各モデルが受け付ける内容は、GET /v1/models の各モデルの supported_parameters に正確に列挙されています。Grok 4.20 以降は logprobs と top_logprobs を無視するため、列挙されません。

provider オブジェクト

既定では、Hyperouter は各チャットリクエストを、そのモデルの価格が最も低い正常なプロバイダーに送信し、同価格の場合は直近の最初のトークンまでの時間が最も短いプロバイダーを選びます。エラーを繰り返すプロバイダーは、回復するまでスキップされます。provider オブジェクトは、OpenRouter のリクエスト形式に従っています。

レスポンス

OpenAI のチャット補完です。id はリクエスト ID で、GET /v1/generations/{id} で照会できます。Hyperouter は provider（リクエストを処理したプロバイダーの公開名。たとえば xAI）と usage.cost（課金額。USD、JSON の数値）を追加します。

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "chat.completion",
  "model": "x-ai/grok-4.7",
  "provider": "xAI",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 8,
    "total_tokens": 17,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "cost": 0.000066
  }
}

プロンプト書き換えモデルは、選択肢を 1 つ、トークン数 0 の usage、およびリクエストごとの固定の cost で応答します。

ストリーミング

"stream": true を指定すると、レスポンスは OpenAI のチャンク形式のサーバー送信イベントのストリームになり、data: [DONE] で終わります。stream_options.include_usage を設定すると、[DONE] の直前の最後のチャンクに、空の choices 配列と、cost を含む usage オブジェクト、および provider フィールドが含まれます。このチャンクを要求するかどうかにかかわらず、課金のために利用量は常に収集されます。

最初のトークンが届くまでの間、ストリームは接続を維持するために、コメント行 : processing を 15 秒ごとに送信します。SSE クライアントはコメントを無視します。

別のプロバイダーへのフォールバックは、最初のトークンが送信される前にのみ行われます。ストリームの途中でプロバイダーが失敗した場合、ストリームは data: {"error": {...}} に続けて data: [DONE] で終了し、すでに生成されたトークンが課金されます。

課金されるのは、読み取ったかどうかにかかわらず、プロバイダーが生成したトークンです。中断したストリームや、待つのをやめた応答は、プロバイダー側では停止されず、プロバイダーは回答の全体を生成して課金します。Hyperouter はその終わりまで（最大でさらに 5 分間）読み取り、その分を課金します。

リクエストを受け付けたプロバイダーは、それを実行中である可能性があります。その後プロバイダーが応答しなくなった場合（ストリームで 5 分間トークンがない、または max_tokens 分の応答にかかる時間を超えた場合）、または最初のトークンの前に応答が途切れた場合、リクエストは別のプロバイダーには送信されません。コード timeout または upstream_error と error.generation_id を伴う 503 が返り、確保した額が課金され、その記録には usage_estimated: true が付きます。

例

curl https://api.hyperouter.app/v1/chat/completions \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "models": ["x-ai/grok-4.6"],
    "provider": { "sort": "latency" },
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

エラー

画像

どちらも OpenAI の Images API に従い、JSON のボディを受け付けます。/v1/images/edits は OpenAI の JSON 形式を受け付けます。画像は images で、1 〜 5 個の https URL です。OpenAI SDK の images.edit は画像ファイルを multipart/form-data で送信しますが、これも使えます。Hyperouter のエッジが各ファイル（PNG、JPEG、WebP。1 つあたり 20 MiB、1 リクエストあたり 50 MiB）を 3 日間保存し、プロバイダーが取得する推測不能な https://api.hyperouter.app/u/... URL にしたうえで、リクエストを JSON として実行します。動画ファイルは拒否されます（400 invalid_video）。動画は https URL で送信してください。どちらも、下記の共通機能と、モデル固有のパラメーターをトップレベルのフィールドとして受け付けます。

パラメーター

モデルが列挙していない共通機能（seed を持たないモデルでの seed など）は、400 unsupported_parameter で拒否されます。出力と価格が変わってしまうため、黙って無視されることはありません。

レスポンス

{
  "created": 1730000000,
  "data": [{ "url": "https://..." }],
  "usage": { "cost": 0.02 },
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21"
}

Hyperouter はすべての結果を 30 日間保存するため、リンクがベンダーを指すことはありません。30 日を過ぎても記録は残りますが、その outputs は空になります。

結果を待つ

• response_modes に sync を含むモデルでは、リクエストは最大 90 秒間画像を待ち、実際のステータスで応答します。画像を含む 200、またはエラーです。検証、残高、処理能力に関するエラーが先に返され、それぞれ固有のステータスになります。
• 90 秒たっても画像が完成していない場合は、コード timeout とレスポンスヘッダー x-should-retry: false を伴う 503 が返ります。これにより、OpenAI SDK が再試行して 2 枚目の画像を開始することはありません。ジョブは継続し、エラーには generation_id としてその ID が含まれます。結果は GET /v1/generations/{id} をポーリングして取得してください。成功した場合にのみ課金されます。ご自身で安全に再試行するには、Idempotency-Key を送信してください。同じキーでの再試行は、同じジョブを待ちます。
• response_modes が async のみのモデルには、Prefer: respond-async が必要です。これがない場合は、コード async_required の 400 が返ります。

• async を列挙するモデルで、接続を保持し続けることを避けるには、Prefer: respond-async（RFC 7240）を送信します。このヘッダーは繰り返すことができ、他の希望と併記することもできます。たとえば Prefer: wait=10, respond-async です。すぐに 202 が返り、レスポンスヘッダー Preference-Applied: respond-async が付きます。

  { "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21", "status": "queued" }

  GET /v1/generations/{id} をポーリングするか、image.completed または image.failed の Webhook を受け取ります。画像の Webhook が送信されるのは、このヘッダーを付けて送信したジョブのみです。

例

curl https://api.hyperouter.app/v1/images/generations \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "A lighthouse at dusk", "n": 1}'

curl https://api.hyperouter.app/v1/images/edits \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "x-ai/grok-imagine-image", "prompt": "make it night",
       "images": [{"image_url": "https://example.com/photo.png"}]}'

エラー

失敗したジョブの message の末尾には、プロバイダーが理由を返した場合、Provider: の後にその理由が付きます。これにより、プロンプトの拒否、プロバイダーの混雑、障害を区別できます。理由に含まれる URL は <url> に置き換えられます。

画像モデル

一部のモデルは、アカウントへのアクセス許可が必要です。ダッシュボードのモデルリファレンスには、アカウントが呼び出せるすべてのモデルが、パラメーター、価格、備考とともに掲載されています。

動画

動画は OpenAI の Videos API に従っています。動画はジョブです。作成、編集、延長、リミックスの呼び出しは、ステータス queued の Video オブジェクトとともに、すぐに 200 で応答します。ステータスが completed になるまで GET /v1/videos/{id} をポーリングするか、Webhook を受け取ります。Prefer はここでは何も変えません。動画は常に非同期です。

動画を作成する

ボディはすべての動画エンドポイントで JSON です。OpenAI SDK の videos.create が input_reference の画像ファイルを付けて送る形式も受け付け、ファイルは画像の編集と同じ扱いになります。画像と動画はすべて公開ホストへの https URL で、そのままプロバイダーに渡されます。プロバイダーが取得できる必要があり、取得も読み取りもできない URL では、動画は vendor_rejected で失敗し、課金されません。data: URL、http:// URL、IP アドレス、内部名は 400 invalid_image または 400 invalid_video で拒否されます。multipart/form-data のボディは 400 unsupported_content_type で拒否されます。

編集、延長、リミックス

元の動画は完成している必要があります。URL で指定した動画は https URL であり、画像と同様にそのままプロバイダーに渡されます。動画を URL で指定する場合、固定の最大値を持たないモデルでは seconds が必要です。

一覧表示、取得、ダウンロード、削除

Video オブジェクト

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "video",
  "model": "x-ai/grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "prompt": null,
  "seconds": "8",
  "size": "",
  "created_at": 1730000000,
  "completed_at": 1730000137,
  "expires_at": 1732592000,
  "error": null,
  "remixed_from_video_id": null,
  "usage": { "cost": 0.4, "seconds": 8 }
}

動画は、リクエストした秒数に基づいて課金されます。金額は事前に確保され、ジョブが失敗した場合は全額が解放されます。

例：x-ai/grok-imagine-video

モデル x-ai/grok-imagine-video は、プロンプトから動画を作成します。開始画像は任意です。seconds は 1 〜 15 です。価格：1 秒あたり $0.050。

curl https://api.hyperouter.app/v1/videos \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-imagine-video",
    "prompt": "She turns to the camera and smiles",
    "input_reference": { "image_url": "https://example.com/portrait.png" },
    "seconds": 8
  }'

{
  "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "video",
  "model": "x-ai/grok-imagine-video",
  "status": "queued",
  "progress": 0,
  "prompt": "She turns to the camera and smiles",
  "seconds": "8",
  "size": "",
  "created_at": 1730000000,
  "completed_at": null,
  "expires_at": 1732592000,
  "error": null,
  "remixed_from_video_id": null,
  "usage": null
}

このジョブの課金額は 8 × $0.050 = $0.40 なので、精算後のオブジェクトには "usage": {"cost": 0.4, "seconds": 8} と表示されます。

エラー

動画モデル

ダッシュボードのモデルリファレンスには、アカウントが呼び出せるすべての動画モデルが掲載されています。

生成履歴

お客様のリクエスト（種類を問いません）の記録を返します。ステータス、利用量、課金額、所要時間、そして画像と動画では出力への署名付きリンクが含まれます。Prefer: respond-async を付けて送信した画像リクエストのポーリングや、利用額の突き合わせに使用します。プロンプトと生成テキストは記録に含まれません。Hyperouter は、法的義務を果たすためにのみそれらを暗号化して 180 日間保管しており、API もダッシュボードのページもそれらを返しません（プライバシーポリシー）。

パラメーター

レスポンス

{
  "data": {
    "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
    "kind": "chat",
    "model": "x-ai/grok-4.7",
    "provider_name": "xAI",
    "status": "done",
    "created_at": "2026-10-24T08:12:00Z",
    "finished_at": "2026-10-24T08:12:02Z",
    "usage": {
      "input_tokens": 120, "output_tokens": 300, "cache_read_tokens": 0,
      "image": 0, "video_seconds": 0, "cost": 0.00204
    },
    "usage_estimated": false,
    "ttft_ms": 320,
    "latency_ms": 2100,
    "error": null,
    "outputs": []
  }
}

curl https://api.hyperouter.app/v1/generations/0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21 \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

エラー

モデル固有のパラメーター

モデルによっては、他のモデルにはないフィールドを持つものがあります。これらは追加パラメーターです。他のフィールドと同様に、リクエストボディのトップレベルのフィールドとして送信します。どの OpenAI SDK でも送信できます（Python では extra_body、JavaScript では追加のプロパティ）。

GET /v1/models は、各モデルの追加パラメーターを extra_parameters に列挙します。各エントリーには次の項目があります。

ダッシュボードのモデルリファレンスには、アカウントが呼び出せる各モデルの追加パラメーターが記載されています。

ルール

• 既知のパラメーターであっても、そのモデルが持たないものは拒否されます。コード unsupported_parameter の 400 invalid_request_error が返り、param にはフィールド名（たとえば loras）、メッセージは This model does not support "loras". となります。カタログ内のいずれかのモデルが宣言しているパラメーターは、既知とみなされます。同じルールは共通機能（resolution、ratio、audio、seed、negative_prompt、first_frame、last_frame、reference_images、reference_videos、prompt_extend）にも適用されます。出力と価格が変わってしまうため、黙って無視されることはありません。
• 型が誤っている値は、400 invalid_body で拒否されます。param には名前が、メッセージには loras must be of type array. のような文が入ります。
• values の範囲外の値は、400 invalid_body とメッセージ <name> must be one of [...] で拒否されます。
• どのモデルも宣言していないフィールドは、OpenAI の API が未知のフィールドを無視するのと同様に、無視されます。
• すべてのモデルは、パラメーターを自身のスキーマに照らして検証します。許可される値、最小値と最大値、必須フィールド、リストの長さです。スキーマの範囲外の値には、フィールドを示す param を伴う 400 invalid_body が返ります。たとえば seconds must be one of 5, 8. です。
• ベンダーが認めていない組み合わせ（参照メディアとキーフレームの併用など）には、理由を添えた 400 invalid_combination が返ります。これらの検証は、課金が発生する前に行われます。
• resolution や audio のように価格を変えるフィールドは、事前のクレジット確保に織り込まれて価格が計算されるため、確保額は正確です。

共通機能

これらのフィールドは、対応するすべてのモデルで同じ名前です。モデルが受け付けるものは supported_parameters に列挙されます。

プロンプト拡張

"prompt_expand": true を指定すると、生成の前に Hyperouter がモデル向けにプロンプトを書き直します。画像ではより詳しい描写に、動画では秒ごとの台本になります。既定ではオフで、プロンプトは書いたとおりに送られます。受け付けるのは supported_parameters に prompt_expand を含むモデルだけで、画像または動画の作成にのみ使えます。それ以外のモデルや、動画の編集・延長・リミックスでは 400 unsupported_parameter で拒否されます。また、prompt_extend: true とは併用できません（400 invalid_body）。

プロンプト拡張は、Hyperouter がアカウントで有効にした後に使えます。サポートチケットで申請してください。それまでは GET /v1/models がどのモデルにも prompt_expand を表示せず、対応するモデルに prompt_expand: true を送ると 403 permission_error、code feature_not_enabled、param prompt_expand が返ります。料金は確保されず、プロバイダーにも送信されません。

• 生成に使われた内容。 画像のレスポンス、動画オブジェクト、GET /v1/generations/{id} には、モデルが受け取ったプロンプトである expanded_prompt が含まれます。リクエストから 30 日間保持され、その後は null を返します。prompt はお客様が送ったテキストのままです。
• 書き直しを行うモデル。 prompt_expand_model は書き直しを行うチャットモデルを指定します。既定は x-ai/grok-4.6 です。prompt_expand: true と併用した場合のみ有効で、それ以外は 400 invalid_body です。存在しないモデルやチャットモデルでないモデルは 400 unknown_model、アカウントで呼び出せないモデルは 403 model_not_enabled となり、いずれも何かを確保する前に拒否されます。画像を読めるモデルにはリクエストの画像が渡され、読めないモデルはテキストだけから書き直します。
• 料金。 書き直しは同じリクエストで課金され、使用したトークンに、書き直したモデル（prompt_expand_model、指定がなければ x-ai/grok-4.6）のトークン単価が適用されます。その上限額は生成分とあわせて事前に確保されます。各モデルの詳細はモデルリファレンスを参照してください。
• 実行されない場合。 書き直しが失敗した、タイムアウトした、または使用できなかった場合は、送信したプロンプトのまま生成し、expanded_prompt: null を返します。料金はかかりません。
• 言語。 動画のセリフは、モデルがその言語を話せる場合、locale（指定がなければ英語）に従います。

書き直しをチャットモデルとして呼び出す

プロンプト拡張が有効なアカウントでは、生成は行わずに書き直しの結果を返すチャットモデルも使えます。モデル名はお使いのモデルリファレンスに記載されています。POST /v1/chat/completions で、user メッセージを 1 つだけ送って呼び出します。そのテキストがプロンプトで、image_url パート（https URL、最大 5 個）が画像です。data: や http:// の URL は 400 invalid_image で、param は messages です。target_model は必須で、prompt_expand を列挙しているモデルを指定します。seconds、locale、negative_prompt は省略できます。画像付きの動画ターゲットは、その画像を最初のフレームとして書かれます。ストリーミングには対応しておらず（stream: true は 400 unsupported_parameter）、それ以外のメッセージは system メッセージも含めて 400 invalid_body になります。

このチャットモデルは常に x-ai/grok-4.6 を使い、prompt_expand_model は受け付けません。choices[0].message.content は JSON 文字列で、{"prompt": "...", "negative_prompt": "..."} に加え、動画ターゲットでは "beats"（1 秒につき 1 行）を含みます。料金は x-ai/grok-4.6 のトークン価格で、usage に表示されます。モデルの指示を出力させようとするプロンプトは 400 prompt_rejected、書き直しが拒否されたか空だった場合は 422 expansion_refused、失敗した場合は 503 upstream_error を返します。いずれも課金されません。

モデレーション

moderation フィールドは OpenAI のものです。/v1/chat/completions、/v1/images/generations、/v1/images/edits、および /v1/videos とその編集、延長、リミックスの呼び出しで使えます。

それ以外の値は拒否されます。400 invalid_request_error、コード invalid_body、param は moderation、メッセージは moderation must be auto or low. です。

low は、Hyperouter が有効にした後にアカウントで利用できます。依頼するには、サポートチケットを作成してください。有効になるまでは、low を指定したリクエストには 403 permission_error、コード moderation_not_enabled、param は moderation が返り、プロバイダーには送信されません。

{
  "model": "qwen/qwen-image-2.0",
  "prompt": "...",
  "moderation": "low"
}

オプトアウトが使用されたかどうかは、レスポンスには示されません。利用規約のポリシーは引き続き適用されます。ベンダーのフィルターが拒否したリクエストは 400 content_rejected で失敗し、課金されません。

Webhook

ポーリングの代わりに、ジョブが終了したときに、お客様のエンドポイントがリクエストを受け取れます。エンドポイントはダッシュボードで追加します。形式は OpenAI の Webhook と同じで、Standard Webhooks 方式で署名されるため、OpenAI SDK で検証できます。

ペイロードに含まれるのは ID のみで、結果、プロンプト、課金額は含まれません。オブジェクトは API キーで取得してください。data.id は、GET /v1/videos/{id} と GET /v1/generations/{id} が受け付ける ID です。raw タスクの場合は、作成時に返された X-Generation-Id です。

{
  "id": "evt_0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21",
  "object": "event",
  "type": "video.completed",
  "created_at": 1761300000,
  "data": { "id": "0194f2c4-7a1e-7b3c-9d02-5f6a1c0e8b21" }
}

ヘッダーと検証

各配信は、content-type: application/json と次のヘッダーを持つ POST です。

• webhook-id：イベント ID。再試行のたびに同じ値のため、重複の排除に使用してください。
• webhook-timestamp：Unix 秒。
• webhook-signature：v1, に続けて、id.timestamp.body の HMAC-SHA256 を base64 エンコードしたもの。鍵はエンドポイントのシークレットです。

署名用のシークレットは whsec_ で始まります。エンドポイントを作成したとき、およびローテーションしたときに、一度だけ表示されます。解析する前の、生のリクエストボディを検証してください。

// Node, with the OpenAI SDK
const event = client.webhooks.unwrap(rawBody, req.headers, process.env.HYPEROUTER_WEBHOOK_SECRET);
if (event.type === "video.completed") {
  const video = await client.videos.retrieve(event.data.id);
}

署名の検証に失敗すると、unwrap は例外を投げます。そのようなリクエストには、エラーのステータスで応答してください。後続の呼び出しでは、この API の他の部分と同じベース URL を使用します。

エンドポイント、リトライ、制限

• エンドポイントは、ポート 443（またはポートなし）の https で、IP アドレスではなくホスト名である必要があります。ホストは公開アドレスに解決される必要があり、Hyperouter は接続時にも再確認します。リダイレクトには従いません。
• 1 つのアカウントのエンドポイントは最大 10 個です。各エンドポイントは、受け取りたいイベントの種類を選択します。
• 10 秒以内の 2xx は成功です。それ以外は、約 5 秒後、1 分後、5 分後、30 分後、2 時間後、5 時間後、10 時間後、10 時間後に再試行され、その後は配信が失敗として記録されます。
• 3 日間すべての配信が失敗したエンドポイントは無効になり、ダッシュボードにその理由が表示されます。受信側を修正した後、再度有効にしてください。
• ダッシュボードには、各エンドポイントの配信が、ステータス、試行回数、最後の HTTP ステータス、最後のエラーとともに一覧表示されます。再送（同じイベント ID）と、テストイベントの送信（data.id がエンドポイントの ID である webhook.test イベントを配信）が用意されています。

MCP サーバー

AI アシスタントは、Model Context Protocol（MCP）を通じて、お客様の Hyperouter アカウントを操作できます。このサーバーが管理するのはダッシュボードの機能で、API キー、アクティビティ、クレジット、チケット、Webhook、モデル一覧です。モデルは実行しません。モデルの呼び出しは、引き続き API キーを使って /v1 に送信します。

サーバーは Streamable HTTP と JSON-RPC 2.0 に対応しています。対応する MCP のリビジョンは 2025-11-25 と 2025-06-18 です。サーバーはステートレスで、セッションはなく、GET /mcp には 405 を返します。

アクセストークン

MCP クライアントは、API キーではなく、ダッシュボードのアクセストークンで認証します。

• トークンはダッシュボードで作成します。名前とスコープを指定し、有効期限は任意で指定します。
• トークンは hr_dt_ で始まり、一度だけ表示されます。Hyperouter が保存するのはそのハッシュのみです。
• アカウントのユーザーが保持できる、期限切れでも失効済みでもないトークンは最大 25 個です。トークンを直ちに停止するには、ダッシュボードで失効させます。
• トークンは /v1 では使えず、API キーは /mcp では使えません。
• トークンは、それを作成したユーザーとして、そのユーザーの権限で動作します。権限はメッセージごとに確認されるため、ロールの変更は次の呼び出しから反映されます。

トークンはベアラートークンとして送信します。

Authorization: Bearer hr_dt_...

プロトコル

通知、またはサーバーへのレスポンスには、ボディなしの 202 を返します。JSON-RPC のバッチはエラー -32600 で拒否されます。メッセージは 1 MiB を超えてはなりません。不明な MCP-Protocol-Version ヘッダーには 400 を返します。ブラウザーからのリクエストは https://dash.hyperouter.app からのものである必要があります。Origin ヘッダーを送信しないクライアントは影響を受けません。

curl https://api.hyperouter.app/mcp \
  -H "Authorization: Bearer $HYPEROUTER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

ツール

tools/list は現在のツールセットを返します。各ツールは 1 つのダッシュボードのルートに対応し、引数用の JSON Schema を持ちます。ツールが対象とするのは次のとおりです。

• アカウントとキー：get_me、list_api_keys、create_api_key、update_api_key。
• アクティビティとクレジット：list_activity、get_activity、get_activity_summary、get_credits、get_topup_fee。
• チケット：list_tickets、create_ticket、get_ticket、reply_to_ticket、close_ticket。
• Webhook：list_webhooks、create_webhook、update_webhook、rotate_webhook_secret、delete_webhook、list_webhook_deliveries、resend_webhook_delivery、send_test_webhook。
• モデル：list_models。
• admin_ プレフィックスを持つスタッフ用ツールは、スタッフ権限を持つユーザーにのみ表示されます。

ツールは、ルートの JSON ボディを格納した 1 つのテキストコンテンツアイテムで応答します。ルートが失敗した場合、結果には isError: true と、<message> (<code>, HTTP <status>) というテキストが入ります。不明なツール、またはお客様のトークンから見えないツールは、JSON-RPC エラー -32602 になります。

承認

アカウントへのクレジット付与のような機密性の高い書き込みは、その場では実行されません。ツールはそれを実行せず、status を approval_required にし、ダッシュボード上の approval_url を添えて応答します。ユーザーはそのリンクを開き、第 2 要素で確認して、操作を承認します。承認は 24 時間で失効します。ユーザーは拒否することもできます。

課金と制限

• リクエストの料金は、プリペイドの USD 残高から、そのリクエストを処理したプロバイダーの定価で、上乗せなしで支払われます。
• 確保してから精算。リクエストの実行前に、Hyperouter はかかりうる最大額を確保します。チャットでは入力に max_tokens を加えた分、画像では要求した枚数、動画では秒数です。完了すると、実際に使われた分が課金され、確保額の残りは解放されます。残高がマイナスになることはありません。
• 失敗したリクエスト、または失敗した画像や動画のジョブは無料です。失敗したフォールバックの試行も無料です。
• すべてのレスポンスに、課金額が usage.cost（USD の JSON 数値）として含まれます。チャット、画像、精算済みの動画、および GET /v1/generations/{id} で確認できます。ダッシュボードでは、すべてのリクエストと、日別・モデル別・キー別の利用額を確認できます。
• 金額は正確です。お金は 10 億分の 1 ドル単位で数えられ、浮動小数点数を経由して丸められることはありません。GET /v1/models の価格は 10 進数の文字列です。
• 現時点ではチャージは手動です。ダッシュボードで、金額、支払い参照番号、支払いのスクリーンショットを添えてチャージの依頼を作成してください。スタッフが支払いを確認して残高に反映し、同じチケットで返信します。
• チャージ手数料。チャージごとに、支払額の 5.5%（最低 $0.80）の手数料がかかり、チャージが反映される際に差し引かれます。$100 の支払いでは $94.50、$10 の支払いでは $9.20 が反映されます。適用される手数料は、チャージを依頼する前に Credits ページに表示され、履歴の各チャージには支払額と手数料が表示されます。リクエスト自体には手数料はかかりません。

レート制限

各アカウントには、1 分あたりのリクエスト数と、同時に処理中のリクエスト数の上限があります。どちらもアカウントのすべての API キーを合算してカウントされ、処理を開始するすべてのリクエストに適用されます。チャット補完、画像と動画の作成、raw の作成が対象です。結果の読み取り（GET /v1/generations/{id}、GET /v1/videos…、raw のタスクのポーリング）はカウントされません。raw のポーリングはプロバイダーごとに別にカウントされ、上限は 1 分あたりのリクエスト数と同じです。

ティアは、チャージ手数料を差し引く前の累計チャージ額に応じて決まります。

現在の上限は Credits ページで確認できます。これらは既定値で、スタッフはプラットフォーム全体または 1 つのアカウントについて変更でき、変更は 1 分以内に反映されます。

いずれかの上限を超えると、クレジットの確保も転送も行われる前にリクエストが拒否され、429、type: rate_limit_error、code: rate_limited、および秒数を示す Retry-After ヘッダーが返ります。メッセージには、到達した上限が示されます。拒否されたリクエストも、その 1 分間にカウントされます。ストリームを含め、処理中のリクエストは、終了するまでカウントされます。

キーの推測に対する防御として、Hyperouter は失敗した API キーの確認をクライアントのアドレスごとに数えます。1 分間に 30 回を超えると、そのアドレスからのすべての /v1 ルートが 15 分間ブロックされ、Retry-After を伴う 429、rate_limit_error、too_many_auth_failures が返ります。有効なキーを使っても、ブロックは解除されません。

サポート

課金、チャージ、API に関するご質問は、ダッシュボードでチケットを作成してください。スタッフが同じスレッドで返信します。[email protected] 宛てにご連絡いただくこともできます。特定のリクエストについて報告する際は、レスポンスの id を添えてください。