Descubrimiento de modelos

Use la página de Modelos o la API de Modelos para inspeccionar los modelos de texto disponibles. Los metadatos del modelo incluyen proveedor, proveedor de servicio, modalidad, longitud de contexto, familias de API soportadas, capacidades soportadas, disponibilidad, límites a nivel de cuenta y precios en créditos.

Endpoint: GET /v1/models Propósito: Listar los modelos disponibles para la cuenta actual.

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

Matriz de capacidades

Matriz de compatibilidad de familias de API

Autenticación

Cada solicitud API usa un token bearer. Guarde las claves en variables de entorno del lado del servidor, rótelas cuando cambie el acceso del equipo y registre los IDs de solicitud para depuración.

Recomendaciones de seguridad de claves

1. Mantenga las claves API en el servidor. No exponga las claves en código de cliente del navegador o móvil.
2. Use claves separadas para desarrollo, staging, producción e integraciones de terceros.
3. Limite las claves por entorno, servicio, cliente o inquilino cuando esté disponible.
4. Rote las claves tras la salida de empleados, cambios de acceso de proveedores o sospecha de fuga.
5. Guarde las claves en gestores de secretos o variables de entorno, no en código fuente.

Agentes de programación

ciyuan_market funciona con agentes de programación y herramientas de desarrollo de IA que soportan endpoints API compatibles con OpenAI o Anthropic. Use alias de enrutamiento como mwf/coding-auto para que ciyuan_market pueda enrutar al mejor modelo de programación disponible sin requerir que los desarrolladores cambien la configuración de la herramienta.

Configuración genérica compatible con OpenAI

Use esta configuración para Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, agentes basados en LangChain, agentes basados en LlamaIndex y runtimes de agentes personalizados compatibles con 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"

Configuración genérica compatible con Anthropic

Use esta configuración para clientes y herramientas compatibles con Claude que esperan el formato 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"

Modelos de agente recomendados

Guía rápida de Cursor

Use el endpoint compatible con OpenAI.

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

Pasos recomendados:

1. Abra la configuración de Cursor.
2. Agregue o habilite la configuración de clave API compatible con OpenAI.
3. Establezca la URL base de OpenAI en https://api.ciyuan-market.com/api/v1.
4. Agregue un modelo personalizado como mwf/coding-auto, mwf/coding-fast o mwf/coding-long.
5. Use un modelo que soporte streaming y llamada a herramientas para el mejor comportamiento del agente.

Solución de problemas:

Guía rápida de Claude Code

Use el endpoint de puerta de enlace compatible con 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 soporta esta ruta compatible con Anthropic para Claude Code y compatibilidad con el SDK de Anthropic:

POST /api/v1/messages

Requisitos recomendados:

Guía rápida de Codex

Use ciyuan_market como proveedor de modelos personalizado compatible con OpenAI.

Configuración de proveedor de ejemplo:

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

Variable de entorno:

export CIYUAN_MARKET_API_KEY="br_xxx"

Modelos recomendados:

Solución de problemas:

Guía rápida de Hermes

Use el endpoint compatible con OpenAI a menos que su despliegue de Hermes esté configurado para otro protocolo.

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"

Política de modelo recomendada:

Guía rápida de OpenClaw

Use el endpoint compatible con OpenAI para la configuración de runtime de agente estilo 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"

Si OpenClaw soporta múltiples proveedores, configure ciyuan_market como proveedor compatible con OpenAI y use alias de enrutamiento de ciyuan_market para la selección de modelos.

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

Lista de verificación de compatibilidad de agentes

Uso de la Consola

La Consola de ciyuan_market es el plano de control operativo para el acceso API, la disponibilidad de modelos, las políticas de enrutamiento, la visibilidad de uso y la administración de facturación. Ofrece a los administradores de cuenta una vista centralizada de claves, modelos, solicitudes, créditos y controles a nivel de cuenta para el tráfico de modelos en producción.

Gestión de claves API

Cree, rote, revoque y etiquete claves API desde la consola. Use claves separadas para desarrollo, staging, producción y servicios individuales para que el uso pueda ser auditado y aislado por entorno o aplicación.

Lista de modelos

Use la página de Modelos para revisar los modelos disponibles para la cuenta. Cada entrada de modelo puede incluir proveedor, proveedor de servicio, modalidad, familias de API soportadas, longitud de contexto, indicadores de capacidad, estado de disponibilidad e información de precios.

Para aplicaciones en producción, verifique las capacidades del modelo antes de habilitar el tráfico. Algunos parámetros y características dependen del modelo y pueden no estar soportados en todas las familias de API.

Uso y registros

La vista de Uso y Registros proporciona visibilidad operativa del tráfico API. Los equipos pueden inspeccionar el volumen de solicitudes, los modelos seleccionados, los destinos de enrutamiento resueltos, el consumo de créditos, la latencia, los códigos de error y los IDs de solicitud.

• Solucionar solicitudes fallidas.
• Identificar cargas de trabajo de alto costo.
• Comparar el uso de modelos entre aplicaciones y entornos.
• Validar el comportamiento de enrutamiento y respaldo.
• Investigar problemas de latencia o disponibilidad del proveedor.
• Proporcionar IDs de solicitud al contactar con soporte.

Cada respuesta API incluye o expone un ID de solicitud de ciyuan_market. Guarde este ID en los registros de su aplicación para hacer que la depuración en producción y la escalada de soporte sean más eficientes.

Respaldo

El respaldo es el mecanismo de resiliencia de ciyuan_market. Cuando el modelo principal o la política de enrutamiento falla, el sistema cambia automáticamente a un modelo de respaldo para seguir procesando la solicitud. Esto mantiene su aplicación receptiva y minimiza el riesgo de interrupción del servicio.

Por qué importa el respaldo

En producción, los servicios de modelos pueden encontrar varios problemas impredecibles:

• Falla del servicio de modelo: la API de origen queda temporalmente no disponible o se agota el tiempo de espera.
• Fluctuación de rendimiento: una alta carga del modelo provoca respuestas lentas o fallidas.
• Falla de enrutamiento: todos los modelos candidatos seleccionados por el enrutamiento inteligente quedan no disponibles.

El respaldo mantiene su aplicación disponible proporcionando una ruta de respaldo confiable.

Ventajas principales

Configuración global de modelo de respaldo

ciyuan_market permite configurar un modelo de respaldo global desde el backend de la consola. Todas las solicitudes usan automáticamente este modelo como respaldo cuando fallan.

Cómo configurarlo:

1. Vaya a la página de configuración de estrategia de ciyuan_market.
2. Busque el ajuste Modelo de respaldo predeterminado.
3. Seleccione su modelo de respaldo global de la lista desplegable.
4. Guarde el ajuste para aplicarlo inmediatamente.

Ventajas de la configuración global:

• Sin cambios en el código: configure una vez y se aplica globalmente, sin necesidad de repetir el ajuste en cada solicitud.
• Gestión centralizada: administre la política de respaldo en un solo lugar para facilitar el ajuste y monitoreo.
• Mantenimiento simplificado: reduce la complejidad del código y la posibilidad de errores de configuración.
• Reemplazo flexible: la configuración de respaldo a nivel de solicitud tiene prioridad y puede anular el ajuste global para escenarios específicos.

Configuración de respaldo a nivel de solicitud

Para escenarios de negocio específicos, puede especificar un modelo de respaldo en una solicitud individual para anular la configuración global.

Especifique el modelo de respaldo con el parámetro router.fallBackModels:

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

Reglas de prioridad

Cuando hay múltiples configuraciones de respaldo, la prioridad va de mayor a menor:

1. router.fallBackModels a nivel de solicitud: el modelo de respaldo especificado en una solicitud individual.
2. Modelo de respaldo predeterminado global: el modelo de respaldo global configurado en la consola.
3. Sin respaldo: si no se configura ninguno, la solicitud devuelve un error al fallar.

Administración de cuenta

Dependiendo del tipo de cuenta, la consola puede incluir habilitación de modelos a nivel de cuenta, controles de revendedor o distribuidor, configuración de facturación y ajustes de acceso. Los administradores pueden usar estos controles para alinear el acceso a modelos, la visibilidad de uso y la responsabilidad de facturación con aplicaciones, cuentas de cliente o unidades de negocio.

Lista de verificación de operaciones de producción

Facturación y créditos

ciyuan_market usa un modelo de facturación basado en créditos para cargas de trabajo de texto, imagen, video y otros modelos soportados. Los créditos proporcionan una unidad unificada para el uso de múltiples modelos y proveedores, de modo que los equipos puedan gestionar el consumo de manera consistente entre modalidades y familias de API.

Los precios detallados de los modelos están disponibles en la página de Modelos o a través de las APIs de metadatos de modelos. Los precios pueden variar según el modelo, proveedor, modalidad, resolución, tipo de token, longitud de salida, duración de la tarea, tipo de cuenta y acuerdo comercial.

Recargar y monedero

Las cuentas pueden añadir créditos de monedero de pago por uso para un uso flexible. Los créditos del monedero se usan después de que se hayan consumido los créditos del plan mensual y los paquetes de recursos, a menos que se aplique una regla de facturación personalizada a la cuenta.

Los créditos del monedero no expiran a menos que se especifique lo contrario en los términos comerciales aplicables. Se cobra una tarifa de servicio al recargar el monedero de pago por uso.

Planes mensuales y paquetes de recursos

Cada usuario o cuenta puede seleccionar un plan mensual activo. Los planes mensuales proporcionan una cantidad definida de capacidad de uso, términos comerciales y configuración de acceso a nivel de cuenta para el período de facturación.

Los usuarios también pueden comprar múltiples paquetes de recursos para capacidad de uso adicional. Los paquetes de recursos pueden separar el uso comprometido del saldo del monedero de pago por uso y son útiles para uso intensivo de texto, imagen, video o cargas de trabajo dedicadas.

Orden de deducción

A menos que se configuren reglas de facturación personalizadas, los créditos se deducen en el siguiente orden:

Para cuentas con términos comerciales personalizados, el orden de deducción, las reglas de expiración, el uso incluido y los precios pueden diferir. Las reglas específicas de cuenta se muestran en la consola o se proporcionan a través del acuerdo comercial.

Precios personalizados

Los precios pueden personalizarse para cada usuario o cuenta. Los clientes empresariales, las cuentas de revendedor, las cuentas de distribuidor y los clientes de alto volumen pueden ser elegibles para precios personalizados. Contacte con ventas para obtener una cotización.

Los precios personalizados pueden configurarse por cuenta, modelo, proveedor, modalidad, región, volumen de uso o acuerdo comercial. Cuando se habilitan precios personalizados, la consola y las APIs de facturación reflejan los precios y reglas de deducción específicos de la cuenta cuando estén disponibles.

Unidades de precio

Diferentes modalidades de modelo usan diferentes unidades de medida. ciyuan_market convierte estas unidades en créditos según las reglas de precios del modelo.

Las unidades de precio pueden variar según el modelo. Consulte siempre la página de detalles del modelo o los metadatos de precios antes de habilitar un modelo en producción.

Atribución de uso

El uso de ciyuan_market puede revisarse por cuenta, clave API, modelo, modalidad o rango de tiempo. Esto permite a los equipos atribuir costos a aplicaciones, entornos, clientes o unidades de negocio internas.

Saldo de créditos

Verifique cuántos créditos están disponibles en su cuenta. El saldo se divide en tres monederos que se deducen en orden: la asignación del plan mensual, los paquetes de recursos comprados y el monedero de pago por uso. También está disponible un total combinado de recursos (plan mensual + paquetes de recursos, excluyendo pago por uso) para rastrear el uso incluido separadamente del gasto de recarga.

Para obtener esto mediante programación, consulte GET /v1/billing/balance en la Referencia API.

Detalles de uso

Revise una lista paginada y cronológica de registros de uso individuales para reportes, monitoreo y asignación interna de costos. Cada registro muestra el modelo, el tipo de modelo (texto, imagen o video), los créditos deducidos y un desglose de qué monedero se usó para cada deducción. Los resultados pueden filtrarse a un rango de tiempo específico.

Para obtener esto mediante programación, consulte GET /v1/usage en la Referencia API.

Historial de transacciones

Use el historial de transacciones para revisar movimientos de créditos, incluyendo recargas, asignaciones de planes, concesiones de paquetes de recursos, deducciones de uso, ajustes y correcciones administrativas.

Para obtener esto mediante programación, consulte GET /v1/billing/transactions en la Referencia API.

Solicitudes fallidas y reembolsos

Los errores de validación, los errores de autenticación y los errores de permisos generalmente no se facturan porque no ocurre ejecución del modelo. Las solicitudes que llegan a un modelo de origen o que generan salida parcial pueden consumir créditos dependiendo del modelo, el proveedor y el estado de la respuesta.

Para tareas asíncronas de imagen y video, el comportamiento de facturación depende de si la tarea fue aceptada, iniciada, completada, fallida o cancelada. La respuesta de detalle de la tarea incluye información de uso cuando se han consumido créditos.

Las recargas, los planes mensuales, los paquetes de recursos y los créditos consumidos no son reembolsables a menos que se especifique lo contrario en el acuerdo comercial aplicable o lo exija la ley.

Referencia API

Convenciones comunes

URL base

Todos los endpoints se sirven bajo el prefijo /v1.

Autenticación

Las llamadas a los endpoints /v1/* usan autenticación de Clave API (no JWT). La clave API se pasa mediante el siguiente encabezado:

Las claves faltantes o inválidas devuelven 401.

Verificación previa de saldo

Todos los endpoints de llamada a modelos ejecutan una verificación previa de saldo antes de la ejecución:

• Un saldo insuficiente devuelve Insufficient credit, asignado a:
  • Protocolo OpenAI: HTTP 400, code = insufficient_quota
  • Protocolo Anthropic: HTTP 402, type = billing_error
• Algunos endpoints también estiman un costo mínimo por modelo para una segunda verificación previa.

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

Endpoint compatible con OpenAI Chat Completions. Soporta streaming y no streaming, llamadas a herramientas, modo JSON y entrada multimodal.

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

Campos de respuesta (no streaming):

Ejemplo de respuesta en streaming:

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

Endpoint compatible con OpenAI Responses. Usa input en lugar de messages, instructions en lugar de un mensaje del sistema, y un bloque text en lugar de 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}
}

Campos de respuesta (no streaming):

El streaming sigue los eventos de la API de Responses:

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

Endpoint compatible con Anthropic Messages. Acepta encabezados x-api-key y anthropic-version: 2023-06-01. Los bloques de contenido soportan text, image, tool_use, tool_result, thinking y redacted_thinking.

Ejemplos de bloque de imagen:

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

Campos de respuesta (no streaming):

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

Devuelve todos los modelos API en línea y habilitados.

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

Campos de cada entrada de modelo (data[]):

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

Devuelve un único modelo con la misma estructura que una entrada de lista. Devuelve HTTP 404 cuando el modelo no existe.

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

Respuesta exitosa: un objeto de modelo único con los mismos campos que una entrada de lista de /v1/models.

Cuando el modelo no existe, devuelve 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

Consulta las resoluciones, relaciones y cantidades máximas soportadas por un modelo de imagen antes de llamar a /v1/image-generations. No requiere autenticación.

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

Consulta los valores de videoType soportados, el rango de duración, las resoluciones y las relaciones de un modelo de video antes de llamar a /v1/video-generations. No requiere autenticación.

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

Descripción de campos de niveles de precio

Los 4 endpoints de consulta de modelos /v1/models, /v1/models/{model}, /v1/image-models y /v1/video-models devuelven el precio de facturación efectivo para el llamante (usuario de API Key), totalmente consistente con el cobro real, y devuelven todos los niveles de precio del modelo.

Diferencia de nomenclatura: /v1/models y /v1/models/{model} usan el estilo OpenAI snake_case (price_tiers); /v1/image-models y /v1/video-models usan camelCase (priceTiers). Ambas estructuras son idénticas.

price_tiers / priceTiers es un array; cada elemento es un nivel de precio:

Los tres tipos de modelo comparten la misma estructura; solo varía el relleno de los campos descriptivos. Los campos no aplicables son null:

Significado del precio: los valores inputPrice / outputPrice / cacheReadPrice / cacheWritePrice devueltos son los precios unitarios de facturación finales para el usuario de API Key actual tras resolver la cadena de precios (chain)→ guidance → precio base, consistentes con el cobro real. El precio unitario que ve el llamante varía según la cadena de precios a la que pertenece (reseller / distributor / empresa / configuración a nivel de usuario).

Deducción real = uso ÷ quantity × precio unitario correspondiente × ratio. Para video por segundos: deducción real = duration × outputPrice × ratio.

Límites y manejo de excepciones (los endpoints de solo lectura no devolverán 500 por problemas de configuración de precios)

Ejemplo de respuesta (/v1/models, modelo de texto):

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

Ejemplo de respuesta (/v1/image-models, modelo de imagen, la estructura de priceTiers es la misma, unit es 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": "por imagen",
          "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

Envía asíncronamente una tarea de generación de imágenes. Devuelve un taskId inmediatamente; recupere el resultado consultando GET /v1/image-generations/{taskId} o a través de un webhook callbackUrl.

El model, los valores soportados de resolution / ratio, el límite superior de count y el límite de subida de imágenes de referencia (fileMax) deben obtenerse primero de GET /v1/image-models. Solo se aceptan los valores anunciados por la especificación de ese modelo.

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

Respuestas de error:

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

Consulta una tarea de generación de imágenes. status es pending / success / failed. images es un arreglo de URLs de imágenes serializado en JSON; text contiene cualquier descripción de texto adjunta por el modelo (por ejemplo, salida multimodal de Gemini), null en caso contrario.

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

Campos de respuesta data:

Tarea no encontrada:

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

Si se proporcionó callbackUrl al enviar, el servidor envía el resultado final success / failed a través del webhook con la misma estructura de data.

Ejemplo completo (envío + consulta)

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

Envía asíncronamente una tarea de generación de video. Devuelve un taskId inmediatamente; recupere el resultado consultando GET /v1/video-generations/{taskId} o a través de un webhook callbackUrl.

El model, los valores permitidos de videoType, el rango de duración (videoDurationMin/Max), la resolution / ratio soportadas y el límite de subida de recursos de referencia (fileMax) deben obtenerse primero de GET /v1/video-models. Solo se aceptan los códigos de videoType listados en allowedVideoTypes de ese modelo.

Ejemplos para cada videoType:

1. Texto a video (videoType=1)

Genera un video solo a partir de un prompt de texto; no se necesitan recursos de referencia.

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. Imagen a video - primer frame (videoType=2)

Proporcione un único frame inicial en imageUrls; el modelo genera un video que comienza desde ese 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. Imagen a video - primer y último frame (videoType=3)

Proporcione tanto el primer como el último frame en imageUrls (orden: [primero, último]); el modelo genera un video de transición entre los dos 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. Imagen a video - referencia (videoType=4)

Proporcione una o más imágenes de referencia en imageUrls; el modelo usa su estilo/contenido como referencia (no como primer/último frame forzado) para generar el 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. Toda referencia (videoType=5)

Referencias mixtas de imagen / video / audio. Referencie recursos por posición en el prompt: la 1ª entrada en imageUrls es @图片 1, la 1ª en videoUrls es @视频 1, la 1ª en audioUrls es @音频 1. videoUrls también acepta cadenas de URL simples.

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

Respuesta de envío (los cinco tipos):

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

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

Consulta una tarea de generación de video. status es pending / success / failed; videoUrl es la URL del video generado y lastFrameUrl es la URL del último frame (escenarios de image-to-video).

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

Campos de respuesta data:

Si se proporcionó callbackUrl al enviar, el servidor envía el resultado final a través del webhook con la misma estructura de data.

Ejemplo completo (envío + consulta)

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

Devuelve el saldo de la cuenta dividido en tres monederos: plan mensual, paquetes de recursos y crédito de pago por uso.

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

Campos de respuesta:

Campos de WalletDetailVO::

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

Detalles de facturación de llamadas a modelos paginadas, con instantánea por precio (priceSnapshotId), ordenados por tiempo de creación del orden de forma descendente. Solo se devuelven los registros de cobro normales (reason = model usage).

Parámetros de consulta:

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"

Contenedor de respuesta:

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

Campos de UsageDetailVO:

Campos de CreditDetailItem:

Convención de valores nulos: solo se completan los campos relevantes para cada modelType; el resto son null. text completa los campos de tokens; image completa imageCount/imageResolution/imageRatio; video completa videoResolution/videoRatio/videoDurationSec.

Ejemplo de respuesta:

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

Lista paginada de las transacciones de recarga pagadas (status=2) del usuario actual, ordenadas por created_at de forma descendente.

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"

Contenedor de respuesta:

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

Campos de TransactionVO:

Campos de TransactionVO:

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

Operativo

Errores

ciyuan_market devuelve códigos de error estables para que las aplicaciones puedan manejar reintentos, respaldos, problemas de facturación y depuración de forma consistente.

Los endpoints compatibles con proveedores intentan preservar la forma de error de la familia de API original cuando es posible. Los endpoints nativos de ciyuan_market usan el objeto de error de ciyuan_market.

Mapeo de estados HTTP y códigos de error

Códigos de error comunes

Características

• 🤖 Chat multi-API: admite endpoints compatibles con OpenAI Chat Completions, Anthropic Messages y OpenAI Responses
• 🖼️ Generación multimodal: además del chat de texto, admite tareas asíncronas de generación de imagen y video (texto a, imagen a, primer/último cuadro, activo de referencia)
• 🔍 Consulta de modelos y cuenta: liste los modelos disponibles, los detalles de modelos, el saldo de la cuenta, los detalles de uso/facturación y las transacciones de recarga
• 🔑 Clave enviada mediante encabezado: cada llamada lee la clave API desde el encabezado de la solicitud, de modo que una sola implementación puede compartirse entre varias cuentas — el servidor nunca persiste ni almacena en caché ninguna clave

Inicio rápido

Úselo en Claude Code (recomendado). Agregue -s user para registrarlo en el ámbito de usuario (disponible en todos sus proyectos).

Paso 1: agregar la conexión

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

Paso 2: verificar la conexión

claude mcp list          # debería mostrar ✓ Connected
claude mcp get ciyuanmarket  # debería mostrar Scope: User config (available in all your projects)

Paso 3: empezar a usarlo

Puede pedirle a Claude cosas como:

• "Usa ciyuan_market para llamar a claude-sonnet-5 y escribe un poema sobre el otoño"
• "Lista los modelos disponibles en mi cuenta de ciyuan_market"
• "Consulta mi saldo y uso reciente en ciyuan_market"
• "Usa ciyuan_market para generar una imagen de una ciudad cyberpunk de noche"

Claude llamará automáticamente a la herramienta MCP correspondiente y devolverá el resultado.

Uso con Claude Desktop

Agregue esto a la sección mcpServers:

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

Uso con Codex CLI

Recomendado: use env_http_headers para leer la clave desde una variable de entorno

Primero exporte la variable de entorno en su shell:

export CIYUAN_MARKET_API_KEY=<su clave API de ciyuan_market>

Luego, en ~/.codex/config.toml:

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

Alternativa: use http_headers para escribir la clave directamente en la configuración (útil si no desea gestionar una variable de entorno aparte, pero tenga en cuenta que la clave quedará almacenada en texto plano en el archivo de configuración):

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

Si lo agrega mediante la interfaz de configuración de Codex:

• Tipo: HTTP / Streamable HTTP
• Nombre: ciyuanmarket
• URL: https://api.ciyuan-market.com/mcp
• Nombre del encabezado: X-Ciyuanmarket-Api-Key
• Valor del encabezado: su clave API de ciyuan_market

Verificar la conexión

Después de iniciar Codex CLI, el comando /mcp lista los servidores MCP configurados y su estado de conexión — solo confirme que se cargó correctamente. El patrón de uso coincide con el de Claude: Codex elige automáticamente la herramienta adecuada.

Si su archivo de configuración ya tiene otros servidores MCP, agregue este al mismo nivel. Cierre por completo y vuelva a abrir Claude Desktop después de editar.

Herramientas

Este servidor MCP ofrece 14 herramientas, agrupadas en cinco categorías:

1. Chat

1. chat_completion — Chat Completions

Envía una única solicitud de chat y devuelve la respuesta completa del modelo (sin streaming). Además de texto, también acepta imágenes para comprensión visual (el modelo debe soportar vision) — cambia el content del mensaje de string a un array de bloques de contenido mezclando text e image_url.

Entrada multimodal (text / image / video)

Entrada de imagen (URL):

{"role": "user", "content": [
  {"type": "text", "text": "¿Qué hay en esta imagen?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Entrada de imagen (Base64):

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

Formatos soportados: PNG, JPEG, GIF (solo el primer fotograma), WebP. Límite de tamaño por imagen 20MB.

Nota: las imágenes grandes en Base64 producen cadenas muy largas y pueden fallar por un cuerpo de solicitud demasiado grande; se recomienda pasar imágenes por URL.

El parámetro detail (opcional, definido en el objeto image_url) controla la fidelidad del procesamiento de la imagen: "auto" (predeterminado — el modelo decide según el tamaño) / "low" (miniatura 512x512, rápido y barato, bueno para clasificación simple) / "high" (resolución total, bueno para texto pequeño / detalles). El array content de un mensaje puede contener varios bloques image_url para pasar varias imágenes.

Video input (URL):

{"role": "user", "content": [
  {"type": "text", "text": "Describe lo que sucede en este 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>"}}

Los modelos que admiten entrada de video en ciyuan_market incluyen algunos modelos de las series Qwen, Doubao (dola-seed), Kimi, MiniMax — verifica input_modalities devuelto por list_models. El estándar oficial Chat Completions de OpenAI no admite video nativamente, pero la pasarela ciyuan_market lo admite a través de

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

formato de extensión. Este formato es consistente con el formato video_url utilizado por OpenRouter, NVIDIA NIM, vLLM y otras plataformas.

2. create_message — Compatible con Anthropic Messages

Llama al endpoint compatible con Anthropic Messages (sin streaming). Los bloques de contenido soportan text, image, tool_use, tool_result, thinking, redacted_thinking. Las imágenes se pasan mediante bloques de contenido

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

.

Entrada multimodal (text / image / video)

La entrada de imagen soporta tres tipos de source:

1. Codificación Base64 (nota: el campo data es una string Base64 pura, sin el prefijo data:); media_type soporta image/jpeg, image/png, image/gif, image/webp:

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

2. Referencia por URL:

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

3. File ID (primero sube la imagen vía la Files API con purpose="vision" para obtener un file_id):

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

El array content de un mensaje puede contener varios bloques image para pasar varias imágenes.

Nota: las imágenes grandes en Base64 producen cadenas muy largas y pueden fallar por un cuerpo de solicitud demasiado grande; se recomienda pasar imágenes por URL.

Entrada de vídeo: la API Anthropic Messages no soporta archivos de vídeo nativamente. Para comprensión de vídeo, primero extrae fotogramas clave con ffmpeg o similar, luego pasa cada fotograma como un bloque de contenido image. Algunas pasarelas compatibles pueden extender el soporte a

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

y similares — consulta la documentación de tu pasarela. For models supporting video input on ciyuan_market (check input_modalities via list_models), use chat_completion or create_response for native video support.

3. create_response — Compatible con OpenAI Responses

Usa input en lugar de messages, instructions en lugar del mensaje del sistema y text.format en lugar de response_format. Además de texto, también acepta imágenes para comprensión visual (el modelo debe soportar vision) — define input como un array de objetos mensaje cuyo content es un array de bloques de contenido que mezcla texto e imágenes.

Entrada multimodal (text / image / video)

Nota: la Responses API usa los tipos de bloque de contenido input_text / input_image / input_video (no text / image_url / video_url de Chat Completions), y image_url / video_url es un string directo, no un objeto anidado.

Entrada de imagen (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "¿Qué hay en esta imagen?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Entrada de imagen (Base64):

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

Formatos soportados: PNG, JPEG, GIF (solo el primer fotograma), WebP. Límite de tamaño por imagen 20MB.

Nota: las imágenes grandes en Base64 producen cadenas muy largas y pueden fallar por un cuerpo de solicitud demasiado grande; se recomienda pasar imágenes por URL.

Entrada de imagen (File ID):

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

— el file_id se obtiene subiendo la imagen vía la Files API con purpose="vision".

El parámetro detail (opcional, en el objeto input_image) controla la fidelidad del procesamiento: "auto" (predeterminado) / "low" (miniatura 512x512, rápido y barato) / "high" (resolución total, para texto pequeño / detalles) / "original" (resolución original). El array content de un mensaje puede contener varios bloques input_image para varias imágenes.

Video input (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "Describe lo que sucede en este 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>"}

. Los modelos que admiten entrada de video en ciyuan_market incluyen algunos modelos de las series Qwen, Doubao (dola-seed), Kimi, MiniMax — verifica input_modalities devuelto por list_models. El estándar oficial Responses API de OpenAI no admite video nativamente, pero la pasarela ciyuan_market lo admite a través de

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

formato de extensión. Este formato es consistente con el formato input_video utilizado por BytePlus/Volcengine y otras plataformas.

2. Modelos y cuenta

4. list_models — Listar modelos disponibles

Devuelve los modelos disponibles para la cuenta actual, con metadatos de proveedor, modalidad, capacidad y precios. Sin parámetros. Cada elemento de la lista incluye un tramo de precio price_tiers — el precio de facturación efectivo del llamador, coincidente con el cargo real (ver Referencia del campo de tramos de precio) (only some newer models).

5. get_model — Obtener los detalles de un modelo

La respuesta incluye un tramo de precio price_tiers (ver Referencia del campo de tramos de precio); devuelve 404 (sin campos de precio) cuando el modelo no existe.

6. get_balance — Consultar el saldo de la cuenta

Devuelve el uso y el saldo actuales de la cuenta. Sin parámetros.

3. Facturación

7. list_usage — Detalles de uso/facturación de modelos

Detalles de facturación por uso de modelos, paginados, ordenados por fecha de creación del pedido en orden descendente. Solo cargos regulares por uso — sin recargas ni ajustes.

8. list_transactions — Transacciones de recarga/paquete

Transacciones pagadas de recarga / compra de paquete, paginadas, ordenadas por fecha de creación en orden descendente.

4. Generación de imágenes

9. list_image_models — Listar modelos de imagen

Devuelve los modelos de generación de imágenes admitidos, con resolución, relación de aspecto, número máximo de imágenes (maxCount) y número máximo de imágenes de referencia (fileMax). Sin parámetros. Consulte esto antes de generar imágenes — solo puede pasar los valores que publica. Cada elemento de la lista incluye un tramo de precio priceTiers (ver Referencia del campo de tramos de precio).

10. create_image_generation — Enviar una tarea de generación de imágenes

Se envía de forma asíncrona y devuelve inmediatamente un taskId; consume crédito de la cuenta.

11. get_image_generation — Sondear una tarea de imagen

Devuelve: status es pending / success / failed; images es un arreglo en formato de cadena JSON de URLs de imágenes; text lleva cualquier salida adicional del modelo (p. ej. salida multimodal de Gemini).

5. Generación de video

12. list_video_models — Listar modelos de video

Devuelve los modelos de generación de video admitidos, con allowedVideoTypes, rango de duración (videoDurationMin/Max), resolución, relación de aspecto y límite de activos de referencia (fileMax). Sin parámetros. Consulte esto antes de generar video. Cada elemento de la lista incluye un tramo de precio priceTiers (ver Referencia del campo de tramos de precio).

13. create_video_generation — Enviar una tarea de generación de video

Se envía de forma asíncrona y devuelve inmediatamente un taskId; consume crédito de la cuenta.

Significado de video_type:

14. get_video_generation — Sondear una tarea de video

Referencia del campo de tramos de precio

Las salidas de estas 4 herramientas de consulta de modelos — list_models, get_model, list_image_models, list_video_models — devuelven el precio de facturación efectivo del llamador (usuario del API Key), que coincide exactamente con el cargo real, e incluyen todos los tramos de precio del modelo.

Diferencia de nomenclatura: list_models / get_model siguen snake_case de OpenAI (price_tiers); list_image_models / list_video_models siguen camelCase (priceTiers). La estructura es la misma.

price_tiers / priceTiers es un array; cada elemento es un tramo de precio:

Los tres tipos de modelo comparten la misma estructura; solo difieren los campos de descripción, y los campos no aplicables son null:

Significado del precio: los inputPrice / outputPrice / cacheReadPrice / cacheWritePrice devueltos, etc., son los precios unitarios finales de facturación para el usuario actual del API Key, resueltos a través de la cadena de precio (chain) → guidance → precio base, y coinciden con el cargo real. El precio unitario que ve el llamador varía según su cadena de precio (reseller / distributor / empresa / configuración de nivel de usuario).

Cargo real = uso ÷ quantity × precio unitario × ratio. Para facturación de vídeo por segundo: cargo real = duration × outputPrice × ratio.

Casos extremos y manejo de errores (un endpoint de solo lectura nunca devuelve 500 por configuración de precio):

Ejemplo de respuesta (list_models, modelo de texto):

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

Ejemplo de respuesta (list_image_models, modelo de imagen; priceTiers misma estructura, unit es 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": "por imagen",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Ejemplos

Ejemplo 1: una solicitud de chat simple

Pregunte: "Usa ciyuan_market para llamar a claude-sonnet-5 y pregunta qué es el GIL de Python"

La IA llamará a chat_completion con:

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

Ejemplo 2: uso de herramientas mediante el endpoint de Anthropic Messages

Pregunte: "Usa el endpoint Messages de ciyuan_market y deja que el modelo decida si consultar el clima"

La IA llamará a create_message, pasando una definición de tools y tool_choice; la respuesta incluirá un bloque de contenido tool_use.

Ejemplo 3: listar los modelos disponibles

Pregunte: "Lista los modelos en mi cuenta de ciyuan_market"

La IA llamará a list_models, devolviendo IDs, proveedores, modalidades, precios y más para cada modelo disponible.

Ejemplo 4: consultar saldo y uso

Pregunte: "Consulta mi uso de ciyuan_market de este mes"

La IA llamará a get_balance para el saldo, y luego a list_usage (con start_time acotado a este mes) para el desglose de uso.

Ejemplo 5: generar una imagen

Pregunte: "Usa ciyuan_market para generar una imagen de una ciudad cyberpunk de noche"

La IA primero llamará a list_image_models para consultar las especificaciones, luego a create_image_generation para obtener un taskId, y después sondeará get_image_generation para obtener la URL de la imagen.

Ejemplo 6: texto a video

Pregunte: "Usa ciyuan_market para generar un video de 5 segundos de una nebulosa espacial"

La IA primero llamará a list_video_models para consultar las especificaciones, luego a create_video_generation (video_type=1, duration=5), y tras obtener un taskId, sondeará get_video_generation.

Preguntas frecuentes

La llamada a la herramienta falla con "missing ciyuan_market API Key"

• Ejecutó claude mcp add sin --header, o la clave es incorrecta
• Si edita la configuración JSON directamente, el nombre del campo headers es incorrecto (debería ser X-Ciyuanmarket-Api-Key)
• Ejecución local sin la variable de entorno CIYUAN_MARKET_API_KEY configurada

La llamada a la herramienta falla con "ciyuan_market returned 401 unauthorized"

La propia clave API es incorrecta o expiró — regenérela en la consola de ciyuan_market.

Claude no está llamando a las herramientas de ciyuan_market — ¿qué hacer?

• Confirme que la conexión muestre ✓ Connected mediante claude mcp list
• Verifique el estado de la conexión: claude mcp get ciyuanmarket
• Intente ser explícito: "Usa la herramienta chat_completion de ciyuan_market para llamar a claude-sonnet-5 …"

La generación de imagen/video se queda pendiente para siempre

• Sondee las tareas de imagen con get_image_generation y las de video con get_video_generation — tenga en cuenta que el estado de una tarea de video en curso es "running", no "pending"
• La generación toma tiempo, generalmente de unos segundos a decenas de segundos, más para video
• Si pasó un callback_url, la tarea llamará de vuelta al completarse — no es necesario sondear

Errores en list_image_models / list_video_models

Ninguna de las dos herramientas consume crédito por sí misma — un error suele indicar un problema de clave o de red. Primero confirme que list_models funciona normalmente.

Notas

• Nombre del encabezado:MCP envía la clave mediante X-Ciyuanmarket-Api-Key.
• Consumo de crédito:chat_completion / create_message / create_response / create_image_generation / create_video_generation consumen todos crédito de la cuenta — consulte get_balance primero si desea conocer el saldo con anticipación.
• Consulte las especificaciones antes de generar:Los parámetros de generación de imagen/video como model, resolution, ratio, count, duration y video_type solo deben usar los valores publicados por list_image_models / list_video_models, de lo contrario la llamada fallará con un error.
• Sin streaming:Ninguno de los tres endpoints de chat admite streaming — cada uno devuelve el resultado completo de una sola vez.
• Diseño sin estado:Cada solicitud es independiente y no se almacena ninguna sesión; para conversaciones de varios turnos use previous_response_id de create_response o mantenga el historial usted mismo en messages.