Model Discovery

Use the Models page or the Models API to inspect available text models. Model metadata includes vendor, serving provider, modality, context length, supported API families, supported capabilities, availability, account-level limits, and credit pricing.

Endpoint: GET /v1/models Purpose: List models available to the current account.

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

Capability matrix

API family compatibility matrix

Authentication

Every API request uses a bearer token. Store keys in server-side environment variables, rotate them when team access changes, and log request IDs for debugging.

Key security recommendations

1. Keep API keys on the server. Do not expose keys in browser or mobile client code.
2. Use separate keys for development, staging, production, and third-party integrations.
3. Scope keys by environment, service, customer, or tenant when available.
4. Rotate keys after employee departures, vendor access changes, or suspected leakage.
5. Store keys in secret managers or environment variables, not source code.

Coding Agents

ciyuan_market works with coding agents and AI development tools that support OpenAI-compatible or Anthropic-compatible API endpoints. Use routing aliases such as mwf/coding-auto so ciyuan_market can route to the best available coding model without requiring developers to change tool configuration.

Generic OpenAI-compatible setup

Use this setup for Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, LangChain-based agents, LlamaIndex-based agents, and custom OpenAI-compatible agent runtimes.

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"

Generic Anthropic-compatible setup

Use this setup for Claude-compatible clients and tools that expect Anthropic Messages format.

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"

Recommended agent models

Cursor quick guide

Use the OpenAI-compatible endpoint.

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

Recommended steps:

1. Open Cursor settings.
2. Add or enable OpenAI-compatible API key configuration.
3. Set the OpenAI base URL override to https://api.ciyuan-market.com/api/v1.
4. Add a custom model such as mwf/coding-auto, mwf/coding-fast, or mwf/coding-long.
5. Use a model that supports streaming and tool calling for best agent behavior.

Troubleshooting:

Claude Code quick guide

Use the Anthropic-compatible gateway endpoint.

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 supports this Anthropic-compatible path for Claude Code and Anthropic SDK compatibility:

POST /api/v1/messages

Recommended requirements:

Codex quick guide

Use ciyuan_market as a custom OpenAI-compatible model provider.

Example provider configuration:

[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"

Environment variable:

export CIYUAN_MARKET_API_KEY="br_xxx"

Recommended models:

Troubleshooting:

Hermes quick guide

Use the OpenAI-compatible endpoint unless your Hermes deployment is configured for another protocol.

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"

Recommended model policy:

OpenClaw quick guide

Use the OpenAI-compatible endpoint for OpenAI-style agent runtime configuration.

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"

If OpenClaw supports multiple providers, configure ciyuan_market as an OpenAI-compatible provider and use ciyuan_market routing aliases for model selection.

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

Agent compatibility checklist

Using the Console

The ciyuan_market Console is the operational control plane for API access, model availability, routing policies, usage visibility, and billing administration. It gives account administrators a centralized view of keys, models, requests, credits, and account-level controls for production model traffic.

Managing API keys

Create, rotate, revoke, and label API keys from the console. Use separate keys for development, staging, production, and individual services so usage can be audited and isolated by environment or application.

Model list

Use the Models page to review models available to the account. Each model entry may include vendor, serving provider, modality, supported API families, context length, capability flags, availability status, and pricing information.

For production applications, verify model capabilities before enabling traffic. Some parameters and features are model-dependent and may not be supported across all API families.

Usage & logs

The Usage & Logs view provides operational visibility into API traffic. Teams can inspect request volume, selected models, resolved routing targets, credit consumption, latency, error codes, and request IDs.

• Troubleshoot failed requests.
• Identify high-cost workloads.
• Compare model usage across applications and environments.
• Validate routing and fallback behavior.
• Investigate latency or provider availability issues.
• Provide request IDs when contacting support.

Each API response includes or exposes a ciyuan_market request ID. Store this ID in your application logs to make production debugging and support escalation more efficient.

Fallback

Fallback is ciyuan_market's resilience mechanism. When the primary model or routing policy fails, the system automatically switches to a backup model to keep processing the request. This keeps your application responsive and minimizes the risk of service disruption.

Why fallback matters

In production, model services can run into a number of unpredictable issues:

• Model service failure: the upstream API becomes temporarily unavailable or times out.
• Performance fluctuation: high model load leads to slow or failed responses.
• Routing failure: all candidate models selected by smart routing become unavailable.

Fallback keeps your application available by providing a reliable backup path.

Core advantages

Global fallback model configuration

ciyuan_market supports setting a global fallback model from the console backend. All requests automatically use this model as a backup when they fail.

How to configure it:

1. Go to the ciyuan_market strategy settings page.
2. Find the Default Fallback Model setting.
3. Select your global fallback model from the dropdown list.
4. Save the setting to apply it immediately.

Advantages of global configuration:

• No code changes required: configure once and it applies globally, with no need to repeat the setting on every request.
• Centralized management: manage the fallback policy in one place for easier adjustment and monitoring.
• Simplified maintenance: reduces code complexity and the chance of configuration errors.
• Flexible override: request-level fallback configuration takes priority and can override the global setting for specific scenarios.

Request-level fallback configuration

For specific business scenarios, you can specify a fallback model on an individual request to override the global configuration.

Specify the fallback model with the router.fallBackModels parameter:

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

Priority rules

When multiple fallback configurations are present, priority runs from highest to lowest:

1. Request-level router.fallBackModels: the fallback model specified on an individual request.
2. Global Default Fallback Model: the global fallback model configured in the console.
3. No fallback: if neither is configured, the request returns an error on failure.

Account administration

Depending on account type, the console may include account-level model enablement, reseller or distributor controls, billing configuration, and access settings. Administrators can use these controls to align model access, usage visibility, and billing responsibility with applications, customer accounts, or business units.

Production operations checklist

Billing & Credits

ciyuan_market uses a credit-based billing model across text, image, video, and other supported model workloads. Credits provide a unified unit for multi-model and multi-provider usage so teams can manage consumption consistently across modalities and API families.

Detailed model pricing is available on the Models page or through model metadata APIs. Pricing may vary by model, provider, modality, resolution, token type, output length, task duration, account type, and commercial agreement.

Top up & wallet

Accounts may add pay-as-you-go wallet credits for flexible usage. Wallet credits are used after monthly plan credits and resource packs have been consumed, unless a custom billing rule applies to the account.

Wallet credits do not expire unless otherwise specified in applicable commercial terms. Service fee is charged when recharging the pay-as-you-go wallet.

Monthly plans and resource packs

Each user or account can select one active monthly plan. Monthly plans provide a defined amount of usage capacity, commercial terms, and account-level access configuration for the billing period.

Users can also buy multiple resource packs for additional usage capacity. Resource packs can separate committed usage from pay-as-you-go wallet balance and are useful for high-volume text, image, video, or dedicated workload usage.

Deduction order

Unless custom billing rules are configured, credits are deducted in the following order:

For accounts with custom commercial terms, deduction order, expiration rules, included usage, and pricing may differ. Account-specific rules are shown in the console or provided through the commercial agreement.

Custom pricing

Pricing can be customized for each user or account. Enterprise customers, reseller accounts, distributor accounts, and high-volume customers may be eligible for custom pricing. Contact sales for a quote.

Custom pricing can be configured by account, model, provider, modality, region, usage volume, or commercial agreement. When custom pricing is enabled, the console and billing APIs reflect account-specific pricing and deduction rules where available.

Pricing units

Different model modalities use different measurement units. ciyuan_market converts these units into credits according to the model’s pricing rules.

Pricing units may vary by model. Always refer to the model detail page or pricing metadata before enabling a model in production.

Usage attribution

ciyuan_market usage can be reviewed by account, API key, model, modality, or time range. This allows teams to attribute cost to applications, environments, customers, or internal business units.

Credit balance

Check how many credits are available across your account. The balance is split into three wallets that are deducted in order: the monthly plan allowance, purchased resource packs, and the pay-as-you-go wallet. A combined resource total (monthly plan + resource packs, excluding pay-as-you-go) is also available for tracking included usage separately from top-up spending.

To retrieve this programmatically, see GET /v1/billing/balance in the API Reference.

Usage details

Review a paginated, chronological list of individual usage records for reporting, monitoring, and internal cost allocation. Each record shows the model, model type (text, image, or video), the credits deducted, and a breakdown of which wallet each deduction was drawn from. Results can be filtered to a specific time range.

To retrieve this programmatically, see GET /v1/usage in the API Reference.

Transaction history

Use transaction history to review credit movements, including top-ups, plan allocations, resource pack grants, usage deductions, adjustments, and administrative corrections.

To retrieve this programmatically, see GET /v1/billing/transactions in the API Reference.

Failed requests and refunds

Validation errors, authentication errors, and permission errors are generally not billed because no model execution occurs. Requests that reach an upstream model or generate partial output may consume credits depending on the model, provider, and response state.

For async image and video tasks, billing behavior depends on whether the task was accepted, started, completed, failed, or cancelled. The task detail response includes usage information when credits have been consumed.

Top-ups, monthly plans, resource packs, and consumed credits are non-refundable unless otherwise specified in the applicable commercial agreement or required by law.

API Reference

Common conventions

Base URL

All endpoints are served under the /v1 prefix.

Authentication

Calls to /v1/* endpoints use API Key authentication (not JWT). The API Key is passed via the following header:

Missing or invalid keys return 401.

Balance pre-check

All model-calling endpoints run a balance pre-check before execution:

• Insufficient balance returns Insufficient credit, mapped to:
  • OpenAI protocol: HTTP 400, code = insufficient_quota
  • Anthropic protocol: HTTP 402, type = billing_error
• Some endpoints also estimate a minimum cost per model for a second pre-check.

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

OpenAI Chat Completions-compatible endpoint. Supports streaming and non-streaming, tool calls, JSON mode, and multimodal input.

Message fields:

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}
}

Response fields (non-streaming):

Streaming response example:

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-compatible endpoint. Uses input instead of messages, instructions instead of a system message, and a text block instead of response_format.

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}
}

Response fields (non-streaming):

Streaming follows the Responses API events:

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

Anthropic Messages-compatible endpoint. Accepts x-api-key and anthropic-version: 2023-06-01 headers. Content blocks support text, image, tool_use, tool_result, thinking, and redacted_thinking.

Examples:

{ "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}
}

Response fields (non-streaming):

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

Returns all online, enabled API models.

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": "..."
    }
  ]
}

Each model entry (data[]) fields:

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

Returns a single model with the same shape as a list entry. Returns HTTP 404 when the model does not exist.

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

Success response: a single model object with the same fields as a /v1/models list entry.

When the model does not exist, returns 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

Query the resolutions, ratios, and maximum counts supported by an image model before calling /v1/image-generations. No authentication required.

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

Query the supported videoType values, duration range, resolutions, and ratios for a video model before calling /v1/video-generations. No authentication required.

VideoTypeOption fields:

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
    }
  ]
}

Price tier fields

The four model query endpoints /v1/models, /v1/models/{model}, /v1/image-models, and /v1/video-models return the effective billing price for the current caller (API key user), fully consistent with actual charges, and return all price tiers of the model.

Field naming difference: /v1/models and /v1/models/{model} use OpenAI-style snake_case (price_tiers); /v1/image-models and /v1/video-models use camelCase (priceTiers). The structures are identical.

price_tiers / priceTiers is an array; each element is a price tier:

The three model types share the same structure; only the descriptive field values differ. Non-applicable fields are null:

Price meaning: the returned inputPrice / outputPrice / cacheReadPrice / cacheWritePrice values are the final billing unit prices for the current API key user after step-by-step resolution through the price chain (chain)→ guidance → base price, consistent with actual charges. The unit price seen by callers differs based on their pricing chain (reseller / distributor / enterprise / user-level configuration).

Actual deduction = usage ÷ quantity × corresponding unit price × ratio. For per-second video billing: actual deduction = duration × outputPrice × ratio.

Boundary & exception handling (read-only endpoints will not return 500 due to price configuration issues)

Response example (/v1/models, text model):

{
  "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": "per 1k tokens",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Response example (/v1/image-models, image model; priceTiers structure is the same, unit is 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": "per image",
          "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

Asynchronously submit an image generation task. Returns a taskId immediately; retrieve the result by polling GET /v1/image-generations/{taskId} or via a callbackUrl webhook.

The model, supported resolution / ratio values, count upper limit, and reference-image upload limit (fileMax) must be obtained from GET /v1/image-models first. Only values advertised by that model's spec are accepted.

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"}
}

Error responses:

// 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}

Poll an image generation task. status is pending / success / failed. images is a JSON-stringified array of image URLs; text carries any model-attached text description (e.g. Gemini multimodal output), null otherwise.

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
  }
}

Response data fields:

Task not found:

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

If callbackUrl was supplied on submit, the server pushes the final success / failed result via webhook with the same data shape.

Complete example (submit + poll)

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

Asynchronously submit a video generation task. Returns a taskId immediately; retrieve the result by polling GET /v1/video-generations/{taskId} or via a callbackUrl webhook.

The model, allowed videoType values, duration range (videoDurationMin/Max), supported resolution / ratio, and reference-asset upload limit (fileMax) must be obtained from GET /v1/video-models first. Only videoType codes listed in that model's allowedVideoTypes are accepted.

Examples for each videoType:

1. Text to video (videoType=1)

Generate a video from a text prompt only; no reference assets needed.

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. Image to video - first frame (videoType=2)

Provide a single starting frame in imageUrls; the model generates a video starting from that frame.

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. Image to video - first and last frame (videoType=3)

Provide both the first and last frame in imageUrls (order: [first, last]); the model generates a transition video between the two frames.

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. Image to video - reference (videoType=4)

Provide one or more reference images in imageUrls; the model uses their style/content as reference (not as a forced first/last frame) to generate the video.

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. All reference (videoType=5)

Mixed image / video / audio references. Reference assets by position in the prompt: the 1st entry in imageUrls is @图片 1, the 1st in videoUrls is @视频 1, the 1st in audioUrls is @音频 1. videoUrls also accepts plain URL strings.

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
  }'

Submit response (all five types):

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

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

Poll a video generation task. status is pending / success / failed; videoUrl is the generated video URL and lastFrameUrl is the last-frame URL (image-to-video scenarios).

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
  }
}

Response data fields:

If callbackUrl was supplied on submit, the server pushes the final result via webhook with the same data shape.

Complete example (submit + poll)

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

Returns the account balance split into three wallets: monthly plan, resource packs, and pay-as-you-go credit.

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
  }
}

Response fields:

WalletDetailVO fields::

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

Paginated model-call billing details, snapshoted by price (priceSnapshotId), ordered by order creation time descending. Only normal charge records (reason = model usage) are returned.

Query parameters:

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"

Response wrapper:

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

UsageDetailVO fields:

CreditDetailItem fields:

Null-value convention: only the fields relevant to each modelType are populated; the rest are null. text populates the token fields; image populates imageCount/imageResolution/imageRatio; video populates videoResolution/videoRatio/videoDurationSec.

Response example:

{
  "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

Paginated list of the current user's paid (status=2) recharge transactions, ordered by created_at descending.

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"

Response wrapper:

{
  "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
  }
}

Operational

Errors

ciyuan_market returns stable error codes so applications can handle retries, fallbacks, billing issues, and debugging consistently.

Provider-compatible endpoints try to preserve the original API family's error shape where possible. ciyuan_market-native endpoints use the ciyuan_market error object.

HTTP status and error code mapping

Common error codes

Features

• 🤖 Multi-API chat: supports OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses compatible endpoints
• 🖼️ Multimodal generation: besides text chat, supports image and video generation (text-to-, image-to-, first/last frame, reference asset) async tasks
• 🔍 Model & account lookup: list available models, model details, account balance, usage/billing details, and top-up transactions
• 🔑 Key passed via header: each call reads the API key from the request header, so one deployment can be shared by multiple accounts — the server never persists or caches any key

Quickstart

Use it in Claude Code (recommended). Add -s user to register it at user scope (available in all your projects).

Step 1: Add the connection

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

Step 2: Verify the connection

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

Step 3: Start using it

You can ask Claude things like:

• "Use ciyuan_market to call claude-sonnet-5 and write a poem about autumn"
• "List the models available on my ciyuan_market account"
• "Check my ciyuan_market balance and recent usage"
• "Use ciyuan_market to generate a cyberpunk city-at-night image"

Claude will automatically call the matching MCP tool and return the result.

Using it with Claude Desktop

Add this to the mcpServers section:

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

Using it with Codex CLI

Recommended: use env_http_headers to read the key from an environment variable

Export the environment variable in your shell first:

export CIYUAN_MARKET_API_KEY=<your ciyuan_market API key>

Then in ~/.codex/config.toml:

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

Alternative: use http_headers to write the key directly into the config (handy if you don't want to manage a separate env var, but note the key is then stored in plain text in the config file):

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

If adding it through the Codex settings UI:

• Type: HTTP / Streamable HTTP
• Name: ciyuanmarket
• URL: https://api.ciyuan-market.com/mcp
• Header name: X-Ciyuanmarket-Api-Key
• Header value: your ciyuan_market API key

Verify the connection

After starting Codex CLI, the /mcp command lists configured MCP servers and their connection status — just confirm it loaded correctly. The usage pattern matches Claude: Codex automatically picks the right tool.

If your config file already has other MCP servers, append this one at the same level. Fully quit and reopen Claude Desktop after editing.

Tools

This MCP server provides 14 tools, grouped into five categories:

1. Chat

1. chat_completion — Chat Completions

Sends a single chat request and returns the model's full reply (no streaming). Beyond plain text, it also accepts images and video for multimodal understanding (model must support the corresponding vision/video capability — check input_modalities via list_models first) — change the message content from a string to an array of content blocks mixing text with image_url / video_url.

Multimodal input (text / image / video)

Image input (URL):

{"role": "user", "content": [
  {"type": "text", "text": "What's in this image?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Image input (Base64):

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

Supported formats: PNG, JPEG, GIF (first frame only), WebP. Single image size limit 20MB.

Note: Base64-encoded large images produce very long strings and may fail due to an oversized request body; prefer passing images by URL.

The detail parameter (optional, set on the image_url object) controls image processing fidelity: "auto" (default — model decides by image size) / "low" (512x512 thumbnail, fast and cheap, good for simple classification) / "high" (full resolution, good for reading small text / fine detail). A single message's content array may hold multiple image_url blocks to pass several images.

Video input (URL):

{"role": "user", "content": [
  {"type": "text", "text": "Describe what happens in this video."},
  {"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>"}}

Models supporting video input on ciyuan_market include select models from the Qwen, Doubao (dola-seed), Kimi, and MiniMax series — check input_modalities returned by list_models. The official OpenAI Chat Completions standard does not natively support video, but the ciyuan_market gateway supports it via the

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

extension format, consistent with the video_url format used by OpenRouter, NVIDIA NIM, vLLM, and other platforms.

2. create_message — Anthropic Messages compatible

Calls the Anthropic Messages compatible endpoint (no streaming). Content blocks support text, image, tool_use, tool_result, thinking, redacted_thinking. Images are passed via content blocks:

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

Multimodal input (text / image / video)

Image input supports three source types:

1. Base64-encoded (note: the data field is a plain Base64 string, without the data: prefix); media_type supports image/jpeg, image/png, image/gif, image/webp:

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

2. URL reference:

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

3. File ID (first upload the image via the Files API with purpose="vision" to get a file_id):

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

A single message's content array may hold multiple image blocks to pass several images.

Note: Base64-encoded large images produce very long strings and may fail due to an oversized request body; prefer passing images by URL.

Video input: the Anthropic Messages API does not support video files. For video understanding, first extract keyframes with ffmpeg or similar, then pass each frame as an image content block. For models that support video input on ciyuan_market (check input_modalities via list_models), use the chat_completion or create_response interface for native video support.

3. create_response — OpenAI Responses compatible

Uses input instead of messages, instructions instead of a system message, and text.format instead of response_format. Beyond plain text, it also accepts images and video for multimodal understanding (model must support the corresponding vision/video capability — check input_modalities via list_models) — set input to an array of message objects whose content is an array of content blocks mixing text with images/video.

Multimodal input (text / image / video)

Note: the Responses API uses content block types input_text / input_image / input_video (not the text / image_url / video_url of Chat Completions), and image_url / video_url are bare strings, not nested objects.

Image input (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "What's in this image?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Image input (Base64):

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

Supported formats: PNG, JPEG, GIF (first frame only), WebP. Single image size limit 20MB.

Note: Base64-encoded large images produce very long strings and may fail due to an oversized request body; prefer passing images by URL.

Image input (File ID):

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

The file_id is obtained by uploading the image via the Files API with purpose="vision".

The detail parameter (optional, set on the input_image object) controls image processing fidelity: "auto" (default) / "low" (512x512 thumbnail, fast and cheap) / "high" (full resolution, for small text / fine detail) / "original" (original resolution, only some newer models). A single message's content array may hold multiple input_image blocks to pass several images.

Video input (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "Describe what happens in this video."},
  {"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>"}

Models supporting video input on ciyuan_market include select models from the Qwen, Doubao (dola-seed), Kimi, and MiniMax series — check input_modalities returned by list_models. The official OpenAI Responses API standard does not natively support video, but the ciyuan_market gateway supports it via the

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

extension format, consistent with the input_video format used by BytePlus/Volcengine and other platforms.

2. Models & account

4. list_models — List available models

Returns the models available to the current account, with vendor, modality, capability, and pricing metadata. No parameters. Each list entry includes a price_tiers price tier list — the caller's effective billing price, matching actual charges (see Price tier field reference).

5. get_model — Get a single model's details

The response includes a price_tiers price tier list (see Price tier field reference); returns 404 (no price fields) when the model doesn't exist.

6. get_balance — Check account balance

Returns the current account's usage and balance. No parameters.

3. Billing

7. list_usage — Model usage/billing details

Paginated model usage billing details, sorted by order creation time descending. Only regular usage charges — no top-ups or adjustments.

8. list_transactions — Top-up/package transactions

Paginated paid top-up / package purchase transactions, sorted by creation time descending.

4. Image generation

9. list_image_models — List image models

Returns supported image generation models, with resolution, aspect ratio, max image count (maxCount), and max reference image count (fileMax). No parameters. Check this before generating images — you can only pass values it publishes. Each list entry includes a priceTiers price tier list (see Price tier field reference).

10. create_image_generation — Submit an image generation task

Submits asynchronously and immediately returns a taskId; consumes account credit.

11. get_image_generation — Poll an image task

Returns: status is pending / success / failed; images is a JSON string array of image URLs; text carries any extra model output (e.g. Gemini multimodal output).

5. Video generation

12. list_video_models — List video models

Returns supported video generation models, with allowedVideoTypes, duration range (videoDurationMin/Max), resolution, aspect ratio, and reference asset limit (fileMax). No parameters. Check this before generating video. Each list entry includes a priceTiers price tier list (see Price tier field reference).

13. create_video_generation — Submit a video generation task

Submits asynchronously and immediately returns a taskId; consumes account credit.

Meaning of video_type:

14. get_video_generation — Poll a video task

Price tier field reference

The outputs of these 4 model-query tools — list_models, get_model, list_image_models, list_video_models — return the caller's (API Key user's) effective billing price, which matches actual charges exactly, and include all price tiers for the model.

Naming difference: list_models / get_model follow OpenAI snake_case (price_tiers); list_image_models / list_video_models follow camelCase (priceTiers). Both have the same structure.

price_tiers / priceTiers is an array; each element is a price tier:

The three model types share one structure; only the description fields differ, and non-applicable fields are null:

Pricing meaning: the returned inputPrice / outputPrice / cacheReadPrice / cacheWritePrice, etc. are the final billing unit prices for the current API Key user, resolved through the price chain (chain) → guidance → base price, and match actual charges. The unit price a caller sees varies by their pricing chain (reseller / distributor / enterprise / user-level config).

Actual charge = usage ÷ quantity × unit price × ratio. For per-second video billing, actual charge = duration × outputPrice × ratio.

Edge cases & error handling (a read-only endpoint never returns 500 due to price config):

Response example (list_models, text model):

{
  "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": "per 1K tokens",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Response example (list_image_models, image model; priceTiers has the same structure, unit is 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": "per image",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Examples

Example 1: a plain chat request

Ask: "Use ciyuan_market to call claude-sonnet-5 and ask what Python's GIL is"

The AI will call chat_completion with:

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

Example 2: tool use via the Anthropic Messages endpoint

Ask: "Use ciyuan_market's Messages endpoint and let the model decide whether to check the weather"

The AI will call create_message, passing a tools definition and tool_choice; the response will include a tool_use content block.

Example 3: list available models

Ask: "List the models on my ciyuan_market account"

The AI will call list_models, returning IDs, vendors, modalities, pricing, and more for every available model.

Example 4: check balance and usage

Ask: "Check my ciyuan_market usage for this month"

The AI will call get_balance for the balance, then list_usage (with start_time scoped to this month) for the usage breakdown.

Example 5: generate an image

Ask: "Use ciyuan_market to generate a cyberpunk city-at-night image"

The AI will first call list_image_models to check specs, then create_image_generation to get a taskId, then poll get_image_generation for the image URL.

Example 6: text-to-video

Ask: "Use ciyuan_market to generate a 5-second video of a space nebula"

The AI will first call list_video_models to check specs, then create_video_generation (video_type=1, duration=5), and after getting a taskId, poll get_video_generation.

FAQ

Tool call fails with "missing ciyuan_market API Key"

• You ran claude mcp add without --header, or the key is wrong
• If editing the JSON config directly, the headers field name is wrong (should be X-Ciyuanmarket-Api-Key)
• Running locally without the CIYUAN_MARKET_API_KEY environment variable set

Tool call fails with "ciyuan_market returned 401 unauthorized"

The API key itself is wrong or expired — regenerate it in the ciyuan_market console.

Claude isn't calling ciyuan_market tools — what now?

• Confirm the connection shows ✓ Connected via claude mcp list
• Check the connection status: claude mcp get ciyuanmarket
• Try being explicit: "Use ciyuan_market's chat_completion tool to call claude-sonnet-5 …"

Image/video generation stays pending forever

• Poll image tasks with get_image_generation and video tasks with get_video_generation — note that a running video task's status is "running", not "pending"
• Generation takes time, usually a few to tens of seconds, longer for video
• If you passed a callback_url, the task will call back on completion — no need to poll

list_image_models / list_video_models errors

Neither tool consumes credit itself — an error usually points to a key or network issue. First confirm list_models works normally.

Notes

• Header name:MCP passes the key via X-Ciyuanmarket-Api-Key.
• Credit consumption:chat_completion / create_message / create_response / create_image_generation / create_video_generation all consume account credit — check get_balance first if you want to know the balance beforehand.
• Check specs before generating:Image/video generation parameters like model, resolution, ratio, count, duration, and video_type must only use values published by list_image_models / list_video_models, otherwise the call errors out.
• No streaming:None of the three chat endpoints support streaming — each returns the full result at once.
• Stateless design:Every request is independent and no session is stored; for multi-turn conversations use create_response's previous_response_id or maintain history yourself in messages.