モデルの検索

モデルページまたはモデルAPIを使用して、利用可能なテキストモデルを確認します。モデルのメタデータには、ベンダー、サービスプロバイダー、モダリティ、コンテキスト長、対応するAPIファミリー、対応する機能、可用性、アカウントレベルの制限、クレジット価格が含まれます。

エンドポイント: GET /v1/models 目的: 現在のアカウントで利用可能なモデルを一覧表示します。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/models \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

機能マトリックス

APIファミリー互換性マトリックス

認証

すべてのAPIリクエストはベアラートークンを使用します。キーはサーバー側の環境変数に保管し、 チームのアクセス権限に変更があった際はローテーションを行い、デバッグ用にリクエストIDを記録してください。

キーセキュリティの推奨事項

1. APIキーはサーバーに保管してください。ブラウザやモバイルのクライアントコードにキーを公開しないでください。
2. 開発、ステージング、本番、サードパーティ連携それぞれで別々のキーを 使用してください。
3. 利用可能な場合は、環境、サービス、顧客、またはテナントごとにキーのスコープを設定してください。
4. 従業員の退職、ベンダーアクセスの変更、または漏洩が疑われる場合は、 キーをローテーションしてください。
5. キーはソースコードではなく、シークレットマネージャーまたは環境変数に保管してください。

コーディングエージェント

ciyuan_marketは、OpenAI互換またはAnthropic互換のAPIエンドポイントをサポートする コーディングエージェントやAI開発ツールと連携します。mwf/coding-auto などの ルーティングエイリアスを使用すると、開発者がツールの設定を変更することなく、 ciyuan_marketが利用可能な最適なコーディングモデルにルーティングできます。

汎用OpenAI互換セットアップ

Cursor、Codex、Hermes、OpenClaw、Continue、Aider、Cline、 LangChainベースのエージェント、LlamaIndexベースのエージェント、およびカスタムOpenAI互換エージェント ランタイムにこのセットアップを使用してください。

export OPENAI_BASE_URL="https://api.ciyuan-market.com/api/v1"
export OPENAI_API_KEY="$CIYUAN_MARKET_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

汎用Anthropic互換セットアップ

Claude互換クライアントやAnthropic Messagesフォーマットを期待する ツールにこのセットアップを使用してください。

export ANTHROPIC_BASE_URL="https://api.ciyuan-market.com/api/anthropic"
export ANTHROPIC_API_KEY="$CIYUAN_MARKET_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

推奨エージェントモデル

Cursorクイックガイド

OpenAI互換エンドポイントを使用します。

Base URL: https://api.ciyuan-market.com/api/v1
API Key:  CIYUAN_MARKET_API_KEY
Model:    mwf/coding-auto

推奨手順：

1. Cursorの設定を開きます。
2. OpenAI互換APIキー設定を追加または有効化します。
3. OpenAIベースURLの上書きを https://api.ciyuan-market.com/api/v1 に設定します。
4. mwf/coding-auto、mwf/coding-fast、 mwf/coding-long などのカスタムモデルを追加します。
5. 最適なエージェント動作のために、ストリーミングとツール呼び出しをサポートするモデルを使用してください。

トラブルシューティング：

Claude Codeクイックガイド

Anthropic互換ゲートウェイエンドポイントを使用します。

export ANTHROPIC_BASE_URL="https://api.ciyuan-market.com/api/anthropic"
export ANTHROPIC_API_KEY="$CIYUAN_MARKET_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

ciyuan_marketは、Claude CodeおよびAnthropic SDK互換性のためのこの Anthropic互換パスをサポートしています：

POST /api/v1/messages

推奨要件：

Codexクイックガイド

ciyuan_marketをカスタムOpenAI互換モデルプロバイダーとして使用します。

プロバイダー設定の例：

[model_providers.ciyuanmarket]
name = "ciyuan_market"
base_url = "https://api.ciyuan-market.com/api/v1"
env_key = "CIYUAN_MARKET_API_KEY"
wire_api = "responses"

model_provider = "ciyuanmarket"
model = "mwf/coding-auto"

環境変数：

export CIYUAN_MARKET_API_KEY="br_xxx"

推奨モデル：

トラブルシューティング：

Hermesクイックガイド

Hermesデプロイメントが別のプロトコル用に設定されていない限り、 OpenAI互換エンドポイントを使用してください。

export OPENAI_BASE_URL="https://api.ciyuan-market.com/api/v1"
export OPENAI_API_KEY="$CIYUAN_MARKET_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

推奨モデルポリシー：

OpenClawクイックガイド

OpenAIスタイルのエージェントランタイム設定にOpenAI互換エンドポイントを使用します。

export OPENAI_BASE_URL="https://api.ciyuan-market.com/api/v1"
export OPENAI_API_KEY="$CIYUAN_MARKET_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

OpenClawが複数のプロバイダーをサポートしている場合は、ciyuan_marketをOpenAI互換 プロバイダーとして設定し、モデル選択にciyuan_marketのルーティングエイリアスを使用してください。

{
  "provider": "openai-compatible",
  "base_url": "https://api.ciyuan-market.com/api/v1",
  "api_key_env": "CIYUAN_MARKET_API_KEY",
  "model": "mwf/coding-auto"
}

エージェント互換性チェックリスト

コンソールの使用

ciyuan_marketコンソールは、APIアクセス、モデル可用性、 ルーティングポリシー、使用量の可視化、請求管理のための運用管理平面です。 アカウント管理者に、キー、モデル、リクエスト、クレジット、 本番のモデルトラフィックに関するアカウントレベルのコントロールの 一元化されたビューを提供します。

APIキーの管理

コンソールからAPIキーの作成、ローテーション、失効、ラベル付けを行います。開発、ステージング、本番、 個別サービスそれぞれで別々のキーを使用し、使用量を環境やアプリケーションごとに 監査・分離できるようにしてください。

モデル一覧

モデル一覧ページを使用して、アカウントで利用可能なモデルを確認します。各モデルエントリには、 ベンダー、サービングプロバイダー、モダリティ、サポートされるAPIファミリー、コンテキスト長、 機能フラグ、可用性状態、価格情報が含まれる場合があります。

本番アプリケーションでは、トラフィックを有効化する前にモデルの機能を確認してください。 一部のパラメータや機能はモデルに依存し、すべてのAPIファミリーで サポートされるとは限りません。

使用量とログ

使用量とログビューは、APIトラフィックの運用可視性を提供します。チームは リクエスト量、選択されたモデル、解決されたルーティングターゲット、クレジット消費量、 レイテンシ、エラーコード、リクエストIDを調査できます。

• 失敗したリクエストのトラブルシューティング。
• 高コストのワークロードの特定。
• アプリケーションや環境間でのモデル使用量の比較。
• ルーティングとフォールバック動作の検証。
• レイテンシやプロバイダー可用性の問題の調査。
• サポートに連絡する際のリクエストIDの提供。

各APIレスポンスにはciyuan_marketリクエストIDが含まれるか、公開されています。このIDを アプリケーションログに保存して、本番デバッグとサポートエスカレーションをより効率的にしてください。

フォールバック

フォールバックはciyuan_marketのレジリエンスメカニズムです。プライマリモデルまたはルーティングポリシーが 失敗した場合、システムは自動的にバックアップモデルに切り替えてリクエストの処理を継続します。 これによりアプリケーションの応答性を維持し、サービス停止のリスクを最小限に抑えます。

フォールバックが重要な理由

本番環境では、モデルサービスは多くの予測不能な問題に遭遇する可能性があります：

• モデルサービスの障害：上流APIが一時的に 利用できなくなったりタイムアウトしたりします。
• パフォーマンスの変動：高いモデル負荷により、レスポンスが 遅くなったり失敗したりします。
• ルーティングの失敗：スマートルーティングで選択された すべての候補モデルが利用不可になります。

フォールバックは信頼性の高いバックアップパスを提供することで、アプリケーションの可用性を維持します。

主な利点

グローバルフォールバックモデル設定

ciyuan_marketはコンソールのバックエンドからグローバルフォールバックモデルの設定をサポートしています。 すべてのリクエストは失敗時にこのモデルをバックアップとして自動的に使用します。

設定方法：

1. ciyuan_market戦略設定ページに 移動します。
2. デフォルトフォールバックモデル設定を見つけます。
3. ドロップダウンリストからグローバルフォールバックモデルを選択します。
4. 設定を保存して即座に適用します。

グローバル設定の利点：

• コード変更不要：一度設定すればグローバルに適用され、 すべてのリクエストで設定を繰り返す必要はありません。
• 一元管理：フォールバックポリシーを一箇所で管理し、 調整や監視を容易にします。
• メンテナンスの簡素化：コードの複雑さと設定エラーの 可能性を低減します。
• 柔軟な上書き：リクエストレベルのフォールバック設定が優先され、 特定のシナリオでグローバル設定を上書きできます。

リクエストレベルのフォールバック設定

特定のビジネスシナリオでは、個々のリクエストでフォールバックモデルを指定して、 グローバル設定を上書きできます。

router.fallBackModels パラメータでフォールバックモデルを指定します：

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

優先順位ルール

複数のフォールバック設定が存在する場合、優先順位は高から低へ 以下の順になります：

1. リクエストレベルの router.fallBackModels：個々のリクエストで指定されたフォールバックモデル。
2. グローバルデフォルトフォールバックモデル：コンソールで設定された グローバルフォールバックモデル。
3. フォールバックなし：いずれも設定されていない場合、リクエストは 失敗時にエラーを返します。

アカウント管理

アカウントの種類に応じて、コンソールにはアカウントレベルのモデル有効化、 リセラーまたはディストリビューターのコントロール、請求設定、アクセス設定が含まれる場合があります。 管理者はこれらのコントロールを使用して、モデルアクセス、使用量の可視性、 請求責任をアプリケーション、顧客アカウント、または事業単位に合わせることができます。

本番運用チェックリスト

請求とクレジット

ciyuan_marketは、テキスト、画像、動画、その他のサポートされるモデルワークロードにわたり クレジットベースの課金モデルを使用します。クレジットはマルチモデルおよびマルチプロバイダーの 使用量のための統一された単位を提供し、チームがモダリティやAPIファミリー全体で 消費量を一貫して管理できるようにします。

詳細なモデル価格は、モデル一覧ページまたはモデルメタデータAPIで確認できます。 価格は、モデル、プロバイダー、モダリティ、解像度、トークンタイプ、出力長、 タスク時間、アカウントタイプ、商取引契約によって異なる場合があります。

チャージとウォレット

アカウントは柔軟な使用のために従量課金ウォレットクレジットを追加できます。ウォレットクレジットは、 アカウントにカスタム請求ルールが適用されていない限り、月額プランのクレジットと リソースパックが消費された後に使用されます。

ウォレットクレジットは、適用される商取引条件で別途定められていない限り期限切れになりません。 従量課金ウォレットのチャージ時にサービス手数料が発生します。

月額プランとリソースパック

各ユーザーまたはアカウントは1つの有効な月額プランを選択できます。月額プランは、 請求期間中の定義された使用量、商取引条件、アカウントレベルのアクセス設定を提供します。

ユーザーは追加の使用量のために複数のリソースパックを購入することもできます。リソースパックは コミットされた使用量を従量課金ウォレット残高から分離でき、大容量のテキスト、画像、動画、 または専用ワークロードの使用に役立ちます。

課金順序

カスタム請求ルールが設定されていない限り、クレジットは以下の順序で 控除されます：

カスタム商取引条件を持つアカウントでは、控除順序、期限ルール、含まれる使用量、価格が 異なる場合があります。アカウント固有のルールはコンソールに表示されるか、 商取引契約を通じて提供されます。

カスタム価格

価格はユーザーまたはアカウントごとにカスタマイズできます。エンタープライズ顧客、リセラーアカウント、 ディストリビューターアカウント、大規模顧客はカスタム価格の対象となる場合があります。 見積もりについては営業にお問い合わせください。

カスタム価格は、アカウント、モデル、プロバイダー、モダリティ、リージョン、使用量、 または商取引契約ごとに設定できます。カスタム価格が有効な場合、コンソールと請求APIは 利用可能な範囲でアカウント固有の価格と控除ルールを反映します。

価格単位

異なるモデルモダリティは異なる測定単位を使用します。ciyuan_marketはモデルの価格ルールに 従ってこれらの単位をクレジットに変換します。

価格単位はモデルによって異なる場合があります。本番でモデルを有効にする前に、 必ずモデル詳細ページまたは価格メタデータを参照してください。

使用量の帰属

ciyuan_marketの使用量は、アカウント、APIキー、モデル、モダリティ、または時間範囲ごとに 確認できます。これによりチームはコストをアプリケーション、環境、顧客、 内部の事業単位に帰属させることができます。

クレジット残高

アカウント全体で利用可能なクレジット数を確認します。残高は順番に控除される3つの ウォレットに分割されます：月額プラン枠、購入済みリソースパック、従量課金ウォレット。 また、チャージ支出とは別に含まれる使用量を追跡するための、統合リソース合計 （月額プラン＋リソースパック、従量課金を除く）も利用可能です。

プログラムでこれを取得するには、APIリファレンスの GET /v1/billing/balanceを参照してください。

使用量の詳細

レポート、監視、内部コスト配分のための、個々の使用量レコードのページ分割された時系列リストを 確認します。各レコードはモデル、モデルタイプ（テキスト、画像、動画）、控除されたクレジット、 各控除がどのウォレットから引き出されたかの内訳を表示します。結果は特定の時間範囲で フィルターできます。

プログラムでこれを取得するには、APIリファレンスの GET /v1/usageを参照してください。

取引履歴

取引履歴を使用して、チャージ、プラン割り当て、リソースパック付与、使用量控除、調整、 管理上の修正を含むクレジットの動きを確認します。

プログラムでこれを取得するには、APIリファレンスの GET /v1/billing/transactionsを参照してください。

失敗したリクエストと返金

検証エラー、認証エラー、権限エラーは、モデルの実行が発生しないため通常は 課金されません。上流モデルに到達したリクエストや部分的な出力を生成したリクエストは、 モデル、プロバイダー、レスポンス状態に応じてクレジットを消費する場合があります。

非同期の画像および動画タスクの場合、課金動作はタスクが承認、開始、完了、失敗、 キャンセルされたかどうかに依存します。タスク詳細レスポンスには、クレジットが消費された 場合に使用量情報が含まれます。

チャージ、月額プラン、リソースパック、消費済みクレジットは、適用される商取引契約で 別途定められているか法律で要求されていない限り返金不可です。

APIリファレンス

共通規約

ベースURL

すべてのエンドポイントは /v1 プレフィックスの下で提供されます。

認証

/v1/* エンドポイントへの呼び出しは APIキー認証を使用します （JWTではありません）。APIキーは以下のヘッダーで渡されます：

キーが存在しない、または無効な場合は 401 を返します。

残高事前チェック

すべてのモデル呼び出しエンドポイントは実行前に残高事前チェックを行います：

• 残高不足の場合 Insufficient credit を返し、以下にマッピングされます：
  • OpenAIプロトコル：HTTP 400、 code = insufficient_quota
  • Anthropicプロトコル：HTTP 402、type = billing_error
• 一部のエンドポイントは2回目の事前チェックのためにモデルごとの最小コストを見積もります。

POST https://api.ciyuan-market.com/api/v1/chat/completions

OpenAI Chat Completions互換エンドポイント。ストリーミングと非ストリーミング、ツール 呼び出し、JSONモード、マルチモーダル入力をサポートします。

Message フィールド：

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/chat/completions \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
    "stream": false,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1721380000,
  "model": "glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hangzhou is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}

レスポンスフィールド（非ストリーミング）：

ストリーミングレスポンスの例：

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

data: [DONE]

POST https://api.ciyuan-market.com/api/v1/responses

OpenAI Responses互換エンドポイント。messages の代わりに input を、 システムメッセージの代わりに instructions を、response_format の 代わりに text ブロックを使用します。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/responses \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "input": "Describe Hangzhou in one sentence.",
    "instructions": "Be concise.",
    "stream": false
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "model": "glm-5.2",
  "status": "completed",
  "created_at": 1721380000,
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hangzhou is ..."}],
      "status": "completed"
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 18, "total_tokens": 30}
}

レスポンスフィールド（非ストリーミング）：

ストリーミングはResponses APIのイベントに従います:

POST https://api.ciyuan-market.com/api/v1/messages

Anthropic Messages互換エンドポイント。x-api-key と anthropic-version: 2023-06-01 ヘッダーを受け付けます。コンテンツブロックは text、image、tool_use、tool_result、 thinking、redacted_thinking をサポートします。

例：

{ "type": "image", "source": { "type": "base64", "media_type": "...", "data": "..." } }
{ "type": "image", "source": { "type": "url", "url": "..." } }

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/messages \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}]
  }'

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "Hangzhou is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 18}
}

レスポンスフィールド（非ストリーミング）：

GET https://api.ciyuan-market.com/api/v1/models

オンラインの有効なすべてのAPIモデルを返します。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/models \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "display_name": "glm-5.2",
      "created": 1721380000,
      "owned_by": "Zai",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 128000,
      "description": "..."
    }
  ]
}

各モデルエントリ（data[]）のフィールド:

GET https://api.ciyuan-market.com/api/v1/models/{model}

リストエントリと同じ形式の単一モデルを返します。モデルが存在しない場合はHTTP 404を返します。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/models/gpt-5.5 \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

成功レスポンス: /v1/models リストエントリと同じフィールドを持つ単一モデルオブジェクト。

モデルが存在しない場合、HTTP 404を返します:

{"error": {"message": "The model 'xxx' does not exist", "type": "invalid_request_error", "code": "invalid_model_error"}}

GET https://api.ciyuan-market.com/api/v1/image-models

画像モデルがサポートする解像度、比率、最大数を /v1/image-generations の呼び出し前に照会します。認証は不要です。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/image-models \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "image_model",
      "displayName": "GPT Image 1",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "maxCount": 4,
      "fileMax": 10,
      "resolutions": ["720p", "1080p"],
      "ratios": ["1:1", "3:2"]
    }
  ]
}

GET https://api.ciyuan-market.com/api/v1/video-models

動画モデルがサポートする videoType 値、長さの範囲、解像度、比率を /v1/video-generations の呼び出し前に照会します。認証は不要です。

VideoTypeOption のフィールド:

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/video-models \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sora-2",
      "object": "video_model",
      "displayName": "Sora 2",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "allowedVideoTypes": [
        {"code": 1, "name": "text-to-video"},
        {"code": 2, "name": "image-to-video"},
        {"code": 3, "name": "image-to-video (first/last frame)"}
      ],
      "videoDurationMin": 5,
      "videoDurationMax": 10,
      "videoDurationSuggest": [5, 8, 10],
      "resolutions": ["1080p", "720p"],
      "ratios": ["16:9", "9:16"],
      "fileMax": 5
    }
  ]
}

価格ティア項目説明

/v1/models、/v1/models/{model}、/v1/image-models、/v1/video-models の 4 つのモデル照会エンドポイントのレスポンスは、現在の呼び出し元（API Key ユーザー）の有効な課金単価を返します。実際の課金と完全に一致し、かつそのモデルの全価格ティアを返します。

フィールド名の違い：/v1/models / /v1/models/{model} は OpenAI 流のスネークケース（price_tiers）；/v1/image-models / /v1/video-models は camelCase（priceTiers）。構造は同じです。

price_tiers / priceTiers は配列で、各要素は 1 つの価格ティアです：

3 種類のモデル種別で同一の構造を共有し、記述項目の埋め方のみ異なります。該当しない項目は null です：

価格の意味：返される inputPrice / outputPrice / cacheReadPrice / cacheWritePrice などは、価格チェーン（chain）→ guidance → 基礎価格を順に解決した後の、現在の API Key ユーザーに対する最終課金単価であり、実際の課金と一致します。呼び出し元が見る単価は、自身が属する価格チェーン（reseller / distributor / 企業 / ユーザー単位設定）によって異なります。

実際の課金額 = 使用量 ÷ quantity × 対応単価 × ratio。動画が秒単位課金の場合、実際の課金 = duration × outputPrice × ratio。

境界と例外処理（読み取り専用エンドポイントは価格設定の問題で 500 を返しません）

レスポンス例（/v1/models、テキストモデル）：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "1000 トークンあたり",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

レスポンス例（/v1/image-models、画像モデル、priceTiers 構造は同じ、unit は image）：

{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "1 枚あたり",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

POST https://api.ciyuan-market.com/api/v1/image-generations

非同期で画像生成タスクを送信します。taskId を即座に返します。結果は GET /v1/image-generations/{taskId} でポーリングするか、callbackUrl Webhook経由で取得します。

model、サポートされる resolution / ratio 値、 count の上限、参照画像のアップロード上限（fileMax）は、 最初に GET /v1/image-models から取得する必要があります。そのモデルの仕様で提示された値のみが受け付けられます。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/image-generations \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.5",
    "text": "A cat drinking water by the river",
    "count": 1,
    "resolution": "2k",
    "ratio": "1:1",
    "imageUrls": []
  }'

{
  "code": 200,
  "message": "image task is commit",
  "data": {"taskId": "img_xxx"}
}

エラーレスポンス：

// Insufficient credit
{ "code": 500, "message": "Insufficient credit" }

// Model not found
{ "code": 404, "message": "Model not found: xxx" }

GET https://api.ciyuan-market.com/api/v1/image-generations/{taskId}

画像生成タスクをポーリングします。status は pending / success / failed です。images は画像URLのJSON文字列化された配列です。text はモデルが添付したテキスト説明（例: Geminiマルチモーダル出力）を運びます。それ以外の場合は null です。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/image-generations/img_xxx \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "img_xxx",
    "status": "success",
    "errorMessage": null,
    "images": "[\"https://.../1.png\"]",
    "text": null
  }
}

レスポンス data フィールド：

タスクが見つかりません:

{ "code": 500, "message": "task not found" }

送信時に callbackUrl が指定された場合、サーバーは同じ data 構造で最終的な success / failed 結果をWebhook経由でプッシュします。

完全な例（送信 + ポーリング）

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageGenerationExample {
  private static final String BASE = "https://api.ciyuan-market.com/api/v1";
  private static final String API_KEY = System.getenv("CIYUAN_MARKET_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task.
    String body = "{"
        + "\"model\":\"seedream-4.5\","
        + "\"text\":\"A cat drinking water by the river\","
        + "\"count\":1,"
        + "\"resolution\":\"2k\","
        + "\"ratio\":\"1:1\","
        + "\"imageUrls\":[]"
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/image-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status.
    String status = "pending";
    while ("pending".equals(status)) {
      Thread.sleep(15_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      status = extract(poll.body(), "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("image generation failed: " + status);
    }
    // images is a JSON-stringified array of URLs.
    String images = extract(pollResult(http, taskId), "images");
    System.out.println("images = " + images);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }

  private static String pollResult(HttpClient http, String taskId) throws Exception {
    return http.send(HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
        .header("Authorization", "Bearer " + API_KEY).GET().build(),
        HttpResponse.BodyHandlers.ofString()).body();
  }
}

import os
import time
import requests

BASE = "https://api.ciyuan-market.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CIYUAN_MARKET_API_KEY']}"}

# 1. Submit the task.
resp = requests.post(
    f"{BASE}/image-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedream-4.5",
        "text": "A cat drinking water by the river",
        "count": 1,
        "resolution": "2k",
        "ratio": "1:1",
        "imageUrls": [],
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status.
while True:
    time.sleep(15)
    poll = requests.get(f"{BASE}/image-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"image generation failed: {data.get('errorMessage')}")

# images is a JSON-stringified array of URLs.
import json
images = json.loads(data["images"])
print(f"images = {images}")

POST https://api.ciyuan-market.com/api/v1/video-generations

非同期で動画生成タスクを送信します。taskId を即座に返します。結果は GET /v1/video-generations/{taskId} でポーリングするか、callbackUrl Webhook経由で取得します。

model、許可された videoType 値、長さの範囲 （videoDurationMin/Max）、サポートされる resolution / ratio、参照アセットのアップロード上限（fileMax）は、 最初に GET /v1/video-models から取得する必要があります。そのモデルの allowedVideoTypes にリストされた videoType コードのみが受け付けられます。

各 videoType の例：

1. テキストから動画（videoType=1）

テキストプロンプトのみから動画を生成します。参照アセットは不要です。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/video-generations \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 1,
    "text": "A cat jumping on a bed",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0"
  }'

2. 画像から動画 - 先頭フレーム（videoType=2）

imageUrls に単一の開始フレームを指定します。モデルはそのフレームから動画を生成します。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/video-generations \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 2,
    "text": "Happily shaking head",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": ["https://ciyuanmarket-flie.oss-accelerate.aliyuncs.com/test/first-frame.png"]
  }'

3. 画像から動画 - 先頭および末尾フレーム（videoType=3）

imageUrls に先頭フレームと末尾フレームの両方を指定します（順序: [first, last]）。モデルは2つのフレーム間の遷移動画を生成します。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/video-generations \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 3,
    "text": "Put on the hat",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ciyuanmarket-flie.oss-accelerate.aliyuncs.com/test/first-frame.png",
      "https://ciyuanmarket-flie.oss-accelerate.aliyuncs.com/test/last-frame.png"
    ]
  }'

4. 画像から動画 - 参照（videoType=4）

imageUrls に1つ以上の参照画像を指定します。モデルはそれらのスタイル/コンテンツを参照（強制された先頭/末尾フレームとしてではなく）として使用し、動画を生成します。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/video-generations \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 4,
    "text": "Two cats playing together",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "kling-v3-omni-video",
    "imageUrls": [
      "https://ciyuanmarket-flie.oss-accelerate.aliyuncs.com/test/ref-1.png",
      "https://ciyuanmarket-flie.oss-accelerate.aliyuncs.com/test/ref-2.png"
    ]
  }'

5. すべて参照（videoType=5）

画像 / 動画 / 音声の混在参照です。プロンプト内の位置でアセットを参照します: imageUrls の1番目のエントリは @图片 1、videoUrls の1番目は @视频 1、audioUrls の1番目は @音频 1 です。videoUrls はプレーンなURL文字列も受け付けます。

curl --request POST \
  --url https://api.ciyuan-market.com/api/v1/video-generations \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 5,
    "text": "Use the first-person framing of @视频 1 and @音频 1 as background music. First-person tea ad; start frame is @图片 1 ... end frame is @图片 2.",
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "videoUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "audioUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 11
  }'

送信レスポンス（5つのタイプすべて）：

{
  "code": 200,
  "message": "success",
  "data": {"taskId": "vid_xxx"}
}

GET https://api.ciyuan-market.com/api/v1/video-generations/{taskId}

動画生成タスクをポーリングします。status は pending / success / failed です。videoUrl は生成された動画の URLで、lastFrameUrl は末尾フレームのURLです（画像から動画のシナリオ）。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/video-generations/vid_xxx \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "videoUrl": "https://.../out.mp4",
    "lastFrameUrl": null,
    "message": null
  }
}

レスポンス data フィールド：

送信時に callbackUrl が指定された場合、サーバーは同じ data 構造で最終結果をWebhook経由でプッシュします。

完全な例（送信 + ポーリング）

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class VideoGenerationExample {
  private static final String BASE = "https://api.ciyuan-market.com/api/v1";
  private static final String API_KEY = System.getenv("CIYUAN_MARKET_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task (videoType=1: text-to-video).
    String body = "{"
        + "\"videoType\":1,"
        + "\"text\":\"A cat jumping on a bed\","
        + "\"resolution\":\"480p\","
        + "\"ratio\":\"16:9\","
        + "\"duration\":4,"
        + "\"model\":\"seedance-2.0\""
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/video-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status. Video tasks take longer — poll every 20s.
    String status = "pending";
    String lastBody = null;
    while ("pending".equals(status)) {
      Thread.sleep(20_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/video-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      lastBody = poll.body();
      status = extract(lastBody, "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("video generation failed: " + status);
    }
    String videoUrl = extract(lastBody, "videoUrl");
    System.out.println("videoUrl = " + videoUrl);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }
}

import os
import time
import requests

BASE = "https://api.ciyuan-market.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CIYUAN_MARKET_API_KEY']}"}

# 1. Submit the task (videoType=1: text-to-video).
resp = requests.post(
    f"{BASE}/video-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "videoType": 1,
        "text": "A cat jumping on a bed",
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "model": "seedance-2.0",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status. Video tasks take longer — poll every 20s.
while True:
    time.sleep(20)
    poll = requests.get(f"{BASE}/video-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"video generation failed: {data.get('message')}")

print(f"videoUrl = {data['videoUrl']}")
if data.get("lastFrameUrl"):
    print(f"lastFrameUrl = {data['lastFrameUrl']}")

GET https://api.ciyuan-market.com/api/v1/billing/balance

アカウント残高を月額プラン、リソースパック、従量課金クレジットの3つのウォレットに分割して返します。

curl --request GET \
  --url https://api.ciyuan-market.com/api/v1/billing/balance \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

{
  "totalCredit": 128.50,
  "totalResourceCredit": 30.00,
  "wallets": {
    "monthlyPlan": {"id": "pkg_xxx", "credit": 50.00, "name": "Monthly plan"},
    "resourcePacks": [
      {"id": "rp_xxx", "credit": 30.00, "name": "Video resource pack"}
    ],
    "payAsYouGo": 48.50
  }
}

レスポンスフィールド：

WalletDetailVO fields::

GET https://api.ciyuan-market.com/api/v1/usage

モデル呼び出しの課金詳細のページネーションリスト。価格 (priceSnapshotId) ごとにスナップショット化され、注文作成時刻の降順で並べ替えられます。通常の課金レコード (reason = model usage) のみが返されます。

クエリパラメータ：

curl --request GET \
  --url "https://api.ciyuan-market.com/api/v1/usage?page=1&size=20&startTime=2026-07-01T00:00:00&endTime=2026-07-31T23:59:59" \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

レスポンスラッパー：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

UsageDetailVO fields:

CreditDetailItem fields:

Null値の規約: 各 modelType に関連するフィールドのみが設定され、それ以外は null になります。text はトークンフィールドを設定します; image は imageCount/imageResolution/imageRatio を設定します; video は videoResolution/videoRatio/videoDurationSec を設定します。

レスポンス例：

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "priceSnapshotId": "snap_9f3c1a2b",
        "taskId": "task_5e8a1c33",
        "credit": 0.0342,
        "model": "glm-5.2",
        "modelType": "text",
        "inputTokens": 1280,
        "outputTokens": 642,
        "totalTokens": 1922,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": null,
        "videoRatio": null,
        "videoDurationSec": null,
        "orderCreatedAt": "2026-07-18T14:23:11",
        "creditDetails": [
          {
            "credit": 0.0342,
            "deductionSource": "balance",
            "packageName": ""
          }
        ]
      },
      {
        "priceSnapshotId": "snap_a12f77c0",
        "taskId": "task_c71e44a2",
        "credit": 1.8000,
        "model": "seedance-2.0",
        "modelType": "video",
        "inputTokens": null,
        "outputTokens": null,
        "totalTokens": null,
        "cacheReadTokens": null,
        "cacheWriteTokens": null,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": "1080p",
        "videoRatio": "16:9",
        "videoDurationSec": 8,
        "orderCreatedAt": "2026-07-17T22:41:09",
        "creditDetails": [
          {
            "credit": 1.5000,
            "deductionSource": "Monthly Package",
            "packageName": "基础月度套餐"
          },
          {
            "credit": 0.3000,
            "deductionSource": "Resource Package",
            "packageName": "byteplus视频资源包"
          }
        ]
      }
    ],
    "total": 128,
    "current": 1,
    "size": 20,
    "pages": 7
  }
}

GET https://api.ciyuan-market.com/api/v1/billing/transactions

現在のユーザーの支払い済み（status=2）チャージ取引のページネーションリスト。created_at の降順で並べ替えられます。

curl --request GET \
  --url "https://api.ciyuan-market.com/api/v1/billing/transactions?page=1&size=20&startTime=2026-07-01%2000:00:00&endTime=2026-07-31%2023:59:59" \
  --header "Authorization: Bearer $CIYUAN_MARKET_API_KEY"

レスポンスラッパー：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

TransactionVO fields:

TransactionVO fields:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "orderNo": "R20260718abc123",
        "thirdPartyOrderNo": "wx_pay_xxx",
        "amount": 50.00,
        "actualAmount": 48.50,
        "discount": 1.50,
        "paymentMethod": "wechat",
        "serviceFeeAmount": 0.00,
        "paymentChannel": "wechat",
        "source": "recharge",
        "packageName": null,
        "createdAt": "2026-07-18T14:23:11"
      }
    ],
    "total": 28,
    "current": 1,
    "size": 20,
    "pages": 2
  }
}

運用

エラー

ciyuan_marketは安定したエラーコードを返すため、アプリケーションはリトライ、フォールバック、課金の問題、デバッグを一貫して処理できます。

プロバイダ互換エンドポイントは、可能な限り元のAPIファミリーのエラー構造を維持しようとします。ciyuan_marketネイティブエンドポイントはciyuan_marketエラーオブジェクトを使用します。

HTTPステータスとエラーコードのマッピング

一般的なエラーコード

特徴

• 🤖 マルチAPIチャット: OpenAI Chat Completions、Anthropic Messages、OpenAI Responses互換のエンドポイントに対応
• 🖼️ マルチモーダル生成: テキストチャットに加え、画像・動画生成(テキストから、画像から、先頭/末尾フレーム、参照アセット)の非同期タスクに対応
• 🔍 モデル・アカウント情報の取得: 利用可能なモデルの一覧、モデル詳細、アカウント残高、使用量・請求の詳細、チャージ履歴を取得
• 🔑 ヘッダー経由のキー渡し: 各呼び出しはリクエストヘッダーからAPIキーを読み取るため、1つのデプロイを複数アカウントで共有できます — サーバー側でキーを保存・キャッシュすることはありません

クイックスタート

Claude Codeでの利用を推奨します。-s userを追加すると、ユーザースコープで登録されます(すべてのプロジェクトで利用可能)。

ステップ1: 接続を追加する

claude mcp add --transport http ciyuanmarket https://api.ciyuan-market.com/mcp \
  --header "X-Ciyuanmarket-Api-Key: <your ciyuan_market API key>" \
  -s user

ステップ2: 接続を確認する

claude mcp list          # should show ✓ Connected
claude mcp get ciyuanmarket  # should show Scope: User config (available in all your projects)

ステップ3: 使ってみる

Claudeに次のように話しかけてみてください。

• 「ciyuan_marketを使ってclaude-sonnet-5を呼び出し、秋についての詩を書いて」
• 「私のciyuan_marketアカウントで利用可能なモデルを一覧表示して」
• 「私のciyuan_marketの残高と最近の使用量を確認して」
• 「ciyuan_marketを使ってサイバーパンクな夜の都市の画像を生成して」

Claudeは自動的に対応するMCPツールを呼び出し、結果を返します。

Claude Desktopで使う

mcpServersセクションに以下を追加してください。

{
  "mcpServers": {
    "ciyuanmarket": {
      "type": "http",
      "url": "https://api.ciyuan-market.com/mcp",
      "headers": {
        "X-Ciyuanmarket-Api-Key": "<your ciyuan_market API key>"
      }
    }
  }
}

Codex CLIで使う

推奨: env_http_headersを使い、環境変数からキーを読み込む方法

まずシェルで環境変数をエクスポートします。

export CIYUAN_MARKET_API_KEY=<your ciyuan_market API key>

次に~/.codex/config.tomlに以下を記述します。

[mcp_servers.ciyuanmarket]
url = "https://api.ciyuan-market.com/mcp"
env_http_headers = { "X-Ciyuanmarket-Api-Key" = "CIYUAN_MARKET_API_KEY" }

別の方法: http_headersを使い、キーを設定ファイルに直接書き込む方法(専用の環境変数を管理したくない場合に便利ですが、キーが設定ファイルに平文で保存される点に注意してください)

[mcp_servers.ciyuanmarket]
url = "https://api.ciyuan-market.com/mcp"
http_headers = { "X-Ciyuanmarket-Api-Key" = "<your ciyuan_market API key>" }

Codexの設定UIから追加する場合:

• タイプ: HTTP / Streamable HTTP
• 名前: ciyuanmarket
• URL: https://api.ciyuan-market.com/mcp
• ヘッダー名: X-Ciyuanmarket-Api-Key
• ヘッダー値: あなたのciyuan_market APIキー

接続を確認する

Codex CLIを起動後、/mcp コマンドで設定済みのMCPサーバーとその接続状態が一覧表示されます — 正しく読み込まれているか確認するだけです。使い方はClaudeと同じで、 Codexが自動的に適切なツールを選択します。

設定ファイルに他のMCPサーバーが既に登録されている場合は、同じ階層に追記してください。編集後はClaude Desktopを完全に終了して再起動してください。

ツール

このMCPサーバーは14個のツールを提供し、5つのカテゴリーに分類されています。

1. チャット

1. chat_completion — Chat Completions

一度の対話リクエストを送信し、モデルの完全な返信を返します（ストリーミング非対応）。テキストだけでなく、画像と動画を渡してマルチモーダル理解も可能です（モデルが対応する vision/video 能力をサポートしている必要あり — list_models で input_modalities を確認）——メッセージの content を文字列からコンテンツブロック配列に変更し、text と image_url / video_url を混在させます。

マルチモーダル入力（text / image / video）

画像入力（URL 方式）：

{"role": "user", "content": [
  {"type": "text", "text": "この画像に何が写っていますか？"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

画像入力（Base64 方式）：

{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

対応画像形式：PNG、JPEG、GIF（先頭フレームのみ）、WebP。 1 枚の画像サイズ上限 20MB。

注意：大きな画像の Base64 文字列は非常に長くなり、リクエストボディ超過で 失敗する可能性があります。URL 方式の使用を推奨します。

detail パラメータ（任意、image_url オブジェクトに設定）が画像処理精度を制御："auto"（デフォルト、モデルが画像サイズで自動決定）/ "low"（512x512 サムネイル、高速・低消費、単純分類向け）/ "high"（フル解像度、小字読取・細部分析向け）。1 メッセージの content 配列に複数の image_url ブロックを置いて複数画像を渡せます。

Video input (URL):

{"role": "user", "content": [
  {"type": "text", "text": "この動画の内容を説明してください。"},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

Video input (Base64):

{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

ciyuan_market で video 入力をサポートするモデルには Qwen、Doubao（dola-seed）、Kimi、MiniMax シリーズの一部モデルが含まれます。詳細は list_models が返す input_modalities で確認してください。 OpenAI 公式 Chat Completions 標準は動画をネイティブサポートしませんが、ciyuan_market ゲートウェイは

{"type": "video_url", "video_url": {"url": "..."}}

拡張形式で動画入力をサポートします。この形式は OpenRouter、NVIDIA NIM、vLLM などの video_url 形式と一致します。

2. create_message — Anthropic Messages互換

Anthropic Messages 互換インターフェースを呼び出します（ストリーミング非対応）。コンテンツブロックは text、image、tool_use、tool_result、thinking、redacted_thinking をサポート。画像は

{"type": "image", "source": {...}}

コンテンツブロックで渡します。

マルチモーダル入力（text / image / video）

画像入力は 3 種類の source タイプをサポート：

1. Base64 エンコード（注意：data フィールドは純 Base64 文字列で、data: プレフィックスを含まない）。media_type は image/jpeg、image/png、image/gif、image/webp をサポート：

{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. URL 参照：

{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID（事前に Files API で purpose="vision" で画像をアップロードし file_id を取得）：

{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

1 メッセージの content 配列に複数の image ブロックを置いて複数画像を渡せます。

注意：大きな画像の Base64 文字列は非常に長くなり、リクエストボディ超過で 失敗する可能性があります。URL 方式の使用を推奨します。

動画入力：Anthropic Messages API は動画ファイルをサポートしません。動画理解が必要な場合は ffmpeg 等でキーフレームを抽出し、各フレームを image コンテンツブロックとして渡してください。ciyuan_market で動画入力をサポートするモデル（list_models で input_modalities に video が含まれるか確認）の場合は chat_completion または create_response インターフェースを使用してネイティブ動画サポートをご利用ください。

3. create_response — OpenAI Responses互換

messages の代わりに input を、システムメッセージの代わりに instructions を、response_format の代わりに text.format を使います。テキストだけでなく、画像と動画を渡してマルチモーダル理解も可能です（モデルが対応する vision/video 能力をサポートしている必要あり — list_models で input_modalities を確認）——input をメッセージオブジェクト配列にし、content をコンテンツブロック配列でテキストと画像/動画を混在させます。

マルチモーダル入力（text / image / video）

注意：Responses API のコンテンツブロック型は input_text / input_image / input_video を使い（Chat Completions の text / image_url / video_url ではなく）、image_url / video_url はネストオブジェクトではなく直接文字列です。

画像入力（URL 方式）：

[{"role": "user", "content": [
  {"type": "input_text", "text": "この画像に何が写っていますか？"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

画像入力（Base64 方式）：

{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

対応画像形式：PNG、JPEG、GIF（先頭フレームのみ）、WebP。 1 枚の画像サイズ上限 20MB。

注意：大きな画像の Base64 文字列は非常に長くなり、リクエストボディ超過で 失敗する可能性があります。URL 方式の使用を推奨します。

画像入力（File ID 方式）：

{"type": "input_image", "file_id": "<file_id>"}

file_id は Files API で purpose="vision" で画像をアップロードして取得します。

detail パラメータ（任意、input_image オブジェクトに設定）が画像処理精度を制御："auto"（デフォルト）/ "low"（512x512 サムネイル、高速・低消費）/ "high"（フル解像度、小字読取・細部分析向け）/ "original"（原始解像度、一部の新モデルのみ対応）。1 メッセージの content 配列に複数の input_image ブロックを置いて複数画像を渡せます。

Video input (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "この動画の内容を説明してください。"},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

Video input (Base64):

{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

Video input (File ID):

{"type": "input_video", "file_id": "<file_id>"}

ciyuan_market で video 入力をサポートするモデルには Qwen、Doubao（dola-seed）、Kimi、MiniMax シリーズの一部モデルが含まれます。詳細は list_models が返す input_modalities で確認してください。 OpenAI 公式 Responses API 標準は動画をネイティブサポートしませんが、ciyuan_market ゲートウェイは

{"type": "input_video", "video_url": "..."}

拡張形式で動画入力をサポートします。この形式は BytePlus/Volcengine などの input_video 形式と一致します。

2. モデル・アカウント

4. list_models — 利用可能なモデルの一覧

現在のアカウントで利用可能なモデルを、ベンダー、モダリティ、機能、価格などのメタデータとともに返します。パラメータなし。リストの各項目に price_tiers 価格帯が含まれ、現在の呼び出し元の有効な課金価格（実際の課金と一致）を返します（価格帯フィールド説明を参照）。

5. get_model — 単一モデルの詳細を取得

出力に price_tiers 価格帯を含みます（価格帯フィールド説明を参照）。モデルが存在しない場合は 404 を返し、価格フィールドは含みません。

6. get_balance — アカウント残高の確認

現在のアカウントの使用量と残高を返します。パラメータなし。

3. 請求

7. list_usage — モデル使用量・請求の詳細

ページネーション対応のモデル使用量請求詳細を、注文作成時刻の降順で返します。通常の使用料のみで、チャージや調整は含みません。

8. list_transactions — チャージ・パッケージ購入の取引履歴

ページネーション対応の、支払い済みのチャージ/パッケージ購入取引履歴を、作成時刻の降順で返します。

4. 画像生成

9. list_image_models — 画像モデルの一覧

対応する画像生成モデルを、解像度、アスペクト比、最大画像数(maxCount)、最大参照画像数(fileMax)とともに返します。パラメータなし。画像を生成する前に必ず確認してください — ここで公開されている値のみ指定できます。リストの各項目に priceTiers 価格帯を含みます（価格帯フィールド説明を参照）。

10. create_image_generation — 画像生成タスクを送信

非同期で送信し、即座にtaskIdを返します。アカウントのクレジットを消費します。

11. get_image_generation — 画像タスクのポーリング

返却内容: statusはpending / success / failedのいずれか。imagesは画像URLのJSON文字列配列。 textにはモデルからの追加出力(例: Geminiのマルチモーダル出力)が含まれます。

5. 動画生成

12. list_video_models — 動画モデルの一覧

対応する動画生成モデルを、allowedVideoTypes、時間範囲(videoDurationMin/Max)、解像度、アスペクト比、参照アセット数の上限(fileMax)とともに返します。パラメータなし。動画を生成する前に必ず確認してください。リストの各項目に priceTiers 価格帯を含みます（価格帯フィールド説明を参照）。

13. create_video_generation — 動画生成タスクを送信

非同期で送信し、即座にtaskIdを返します。アカウントのクレジットを消費します。

video_typeの意味:

14. get_video_generation — 動画タスクのポーリング

価格帯フィールド説明

list_models、get_model、list_image_models、list_video_models の 4 つのモデル照会ツールの出力は、現在の呼び出し元（API Key ユーザー）の有効な課金価格を返し、実際の課金と完全に一致し、そのモデルのすべての価格帯を含みます。

命名の違い：list_models / get_model は OpenAI のスネークケース（price_tiers）に従い、list_image_models / list_video_models は camelCase（priceTiers）に従います。構造は全く同じです。

price_tiers / priceTiers は配列で、各要素は 1 つの価格帯です：

3 種のモデルタイプは同じ構造を共有し、説明フィールドの充填のみが異なり、該当しないフィールドは null です：

価格の意味：返される inputPrice / outputPrice / cacheReadPrice / cacheWritePrice 等は、価格チェーン（chain）→ guidance → 基準価格を段階的に解決した後の、現在の API Key ユーザー向けの最終課金単価で、実際の課金と一致します。呼び出し元が見る単価は、自身の価格チェーン（reseller / distributor / 企業 / ユーザー単位設定）により異なります。

実際の課金額 = 使用量 ÷ quantity × 該当単価 × ratio。動画の秒単位課金の場合、実際の課金 = duration × outputPrice × ratio。

境界と例外処理（読み取り専用インターフェースは価格設定の問題で 500 を返しません）：

レスポンス例（list_models、テキストモデル）：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "1K token あたり",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

レスポンス例（list_image_models、画像モデル、priceTiers は構造同上、unit は image）：

{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "1 枚あたり",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

使用例

例1: シンプルなチャットリクエスト

質問例: 「ciyuan_marketを使ってclaude-sonnet-5を呼び出し、PythonのGILとは何か聞いて」

AIはchat_completionを次のように呼び出します。

{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "What is Python's GIL?"}]
}

例2: Anthropic Messagesエンドポイントでのツール使用

質問例: 「ciyuan_marketのMessagesエンドポイントを使い、天気を確認するかどうかをモデルに判断させて」

AIはツール定義とtool_choiceを渡してcreate_messageを呼び出します。 レスポンスにはtool_useコンテンツブロックが含まれます。

例3: 利用可能なモデルの一覧表示

質問例: 「私のciyuan_marketアカウントのモデルを一覧表示して」

AIはlist_modelsを呼び出し、利用可能なすべてのモデルのID、ベンダー、モダリティ、価格などを返します。

例4: 残高と使用量の確認

質問例: 「今月の私のciyuan_marketの使用量を確認して」

AIは残高確認のためにget_balanceを呼び出し、続けて使用量の内訳のために list_usage(start_timeを今月に指定)を呼び出します。

例5: 画像の生成

質問例: 「ciyuan_marketを使ってサイバーパンクな夜の都市の画像を生成して」

AIはまずlist_image_modelsでスペックを確認し、次に create_image_generationを呼び出してtaskIdを取得し、その後 get_image_generationをポーリングして画像URLを取得します。

例6: テキストから動画を生成

質問例: 「ciyuan_marketを使って宇宙の星雲の5秒間の動画を生成して」

AIはまずlist_video_modelsでスペックを確認し、次に create_video_generation(video_type=1、duration=5)を呼び出し、 taskIdを取得した後にget_video_generationをポーリングします。

FAQ

ツール呼び出しが「missing ciyuan_market API Key」で失敗する

• claude mcp addを--headerなしで実行した、またはキーが間違っている
• JSON設定ファイルを直接編集している場合、headersフィールド名が間違っている( X-Ciyuanmarket-Api-Keyである必要があります)
• ローカル実行時にCIYUAN_MARKET_API_KEY環境変数が設定されていない

ツール呼び出しが「ciyuan_market returned 401 unauthorized」で失敗する

APIキー自体が間違っているか、期限切れです — ciyuan_marketのコンソールで再生成してください。

Claudeがciyuan_marketのツールを呼び出さない場合は?

• claude mcp listで接続が✓ Connectedと表示されているか確認してください
• 接続状態を確認する: claude mcp get ciyuanmarket
• 明示的に指示してみてください: 「ciyuan_marketのchat_completionツールを使って claude-sonnet-5を呼び出して…」

画像/動画生成がずっとpendingのままになる

• 画像タスクはget_image_generation、動画タスクはget_video_generation でポーリングしてください — なお、実行中の動画タスクのstatusは"running"であり、"pending"ではないことに注意してください
• 生成には時間がかかります。通常は数秒から数十秒、動画の場合はさらに長くなります
• callback_urlを指定していた場合、完了時にコールバックが呼び出されるため、ポーリングは不要です

list_image_models / list_video_modelsがエラーになる

どちらのツールもそれ自体はクレジットを消費しません — エラーは通常、キーまたはネットワークの問題を示しています。まず list_modelsが正常に動作するか確認してください。

注意事項

• ヘッダー名:MCPはX-Ciyuanmarket-Api-Key経由でキーを渡します。
• クレジットの消費:chat_completion / create_message / create_response / create_image_generation / create_video_generationはすべてアカウントのクレジットを消費します — 事前に残高を確認したい場合は get_balanceを先に呼び出してください。
• 生成前にスペックを確認:model、resolution、ratio、count、duration、video_typeなどの画像/動画生成パラメータは、 list_image_models / list_video_modelsが公開している値のみ使用できます。 それ以外の値を指定するとエラーになります。
• ストリーミング非対応:3つのチャットエンドポイントはいずれもストリーミングに対応していません — 各エンドポイントは完全な結果を一度に返します。
• ステートレス設計:各リクエストは独立しており、セッションは保存されません。複数ターンの会話には create_responseの previous_response_idを使うか、messagesで 自分で履歴を管理してください。