Descoberta de modelos

Use a página de Modelos ou a API de Modelos para inspecionar os modelos de texto disponíveis. Os metadados do modelo incluem fornecedor, provedor de serviço, modalidade, comprimento de contexto, famílias de API suportadas, capacidades suportadas, disponibilidade, limites no nível da conta e preço em créditos.

Endpoint: GET /v1/models Objetivo: Listar modelos disponíveis para a conta atual.

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

Matriz de capacidades

Matriz de compatibilidade de famílias de API

Autenticação

Toda solicitação de API usa um token bearer. Armazene as chaves em variáveis de ambiente do lado do servidor, rotacione-as quando o acesso da equipe mudar e registre os IDs de solicitação para depuração.

Recomendações de segurança de chaves

1. Mantenha as chaves API no servidor. Não exponha as chaves no código do navegador ou do cliente móvel.
2. Use separate keys for development, staging, production, and third-party integrations.
3. Defina o escopo das chaves por ambiente, serviço, cliente ou tenant quando disponível.
4. Rotate keys after employee departures, vendor access changes, or suspected leakage.
5. Armazene as chaves em gerenciadores de segredos ou variáveis de ambiente, não no código-fonte.

Agentes de programação

O ciyuan_market funciona com agentes de programação e ferramentas de desenvolvimento de IA que suportam endpoints de API compatíveis com OpenAI ou Anthropic. Use aliases de roteamento como mwf/coding-auto para que o ciyuan_market possa rotear para o melhor modelo de programação disponível sem exigir que os desenvolvedores alterem a configuração da ferramenta.

Configuração genérica compatível com OpenAI

Use esta configuração para Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, agentes baseados em LangChain, agentes baseados em LlamaIndex e runtimes de agentes personalizados compatíveis com 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"

Configuração genérica compatível com Anthropic

Use esta configuração para clientes compatíveis com Claude e ferramentas que esperam o 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

Guia rápido do Cursor

Use o endpoint compatível com OpenAI.

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

Passos recomendados:

1. Abra as configurações do Cursor.
2. Adicione ou ative a configuração de chave API compatível com OpenAI.
3. Defina a substituição da URL base do OpenAI para https://api.ciyuan-market.com/api/v1.
4. Adicione um modelo personalizado como mwf/coding-auto, mwf/coding-fast ou mwf/coding-long.
5. Use um modelo que suporte streaming e chamada de ferramentas para o melhor comportamento do agente.

Solução de problemas:

Guia rápido do Claude Code

Use o endpoint do gateway compatível com 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"

O ciyuan_market suporta este caminho compatível com Anthropic para compatibilidade com Claude Code e SDK Anthropic:

POST /api/v1/messages

Requisitos recomendados:

Guia rápido do Codex

Use o ciyuan_market como um provedor de modelo personalizado compatível com OpenAI.

Exemplo de configuração do provedor:

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

Variável de ambiente:

export CIYUAN_MARKET_API_KEY="br_xxx"

Modelos recomendados:

Solução de problemas:

Guia rápido do Hermes

Use o endpoint compatível com OpenAI, a menos que sua implantação do Hermes esteja configurada para outro 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:

Guia rápido do OpenClaw

Use o endpoint compatível com OpenAI para a configuração de runtime de agente no 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"

Se o OpenClaw suportar múltiplos provedores, configure o ciyuan_market como um provedor compatível com OpenAI e use aliases de roteamento do ciyuan_market para seleção de modelo.

{
  "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 verificação de compatibilidade de agentes

Uso do console

O Console do ciyuan_market é o plano de controle operacional para acesso à API, disponibilidade de modelos, políticas de roteamento, visibilidade de uso e administração de cobrança. Ele oferece aos administradores da conta uma visão centralizada de chaves, modelos, solicitações, créditos e controles no nível da conta para tráfego de modelos em produção.

Gerenciamento de chaves API

Crie, rotacione, revogue e rotule chaves API no console. Use chaves separadas para desenvolvimento, homologação, produção e serviços individuais para que o uso possa ser auditado e isolado por ambiente ou aplicação.

Lista de modelos

Use a página de Modelos para revisar os modelos disponíveis para a conta. Cada entrada de modelo pode incluir fornecedor, provedor de serviço, modalidade, famílias de API suportadas, comprimento de contexto, sinalizadores de capacidade, status de disponibilidade e informações de preço.

Para aplicações em produção, verifique as capacidades do modelo antes de ativar o tráfego. Alguns parâmetros e recursos dependem do modelo e podem não ser suportados em todas as famílias de API.

Uso e logs

A visualização de Uso e Logs fornece visibilidade operacional do tráfego da API. As equipes podem inspecionar o volume de solicitações, modelos selecionados, destinos de roteamento resolvidos, consumo de créditos, latência, códigos de erro e IDs de solicitação.

• Solucione falhas em solicitações.
• Identifique cargas de trabalho de alto custo.
• Compare o uso de modelos entre aplicações e ambientes.
• Valide o comportamento de roteamento e fallback.
• Investigue problemas de latência ou disponibilidade do provedor.
• Forneça IDs de solicitação ao contatar o suporte.

Cada resposta da API inclui ou expõe um ID de solicitação do ciyuan_market. Armazene este ID nos logs da sua aplicação para tornar a depuração de produção e a escalonamento de suporte mais eficientes.

Fallback

O Fallback é o mecanismo de resiliência do ciyuan_market. Quando o modelo principal ou a política de roteamento falha, o sistema alterna automaticamente para um modelo de backup para continuar processando a solicitação. Isso mantém sua aplicação responsiva e minimiza o risco de interrupção do serviço.

Por que o fallback é importante

Em produção, os serviços de modelo podem enfrentar vários problemas imprevisíveis:

• Falha no serviço do modelo: a API upstream fica temporariamente indisponível ou atinge o tempo limite.
• Flutuação de desempenho: alta carga do modelo leva a respostas lentas ou com falha.
• Falha de roteamento: todos os modelos candidatos selecionados pelo roteamento inteligente ficam indisponíveis.

O Fallback mantém sua aplicação disponível fornecendo um caminho de backup confiável.

Principais vantagens

Configuração de modelo de fallback global

O ciyuan_market suporta a definição de um modelo de fallback global no backend do console. Todas as solicitações usam automaticamente este modelo como backup quando falham.

Como configurar:

1. Acesse a página de configurações de estratégia do ciyuan_market.
2. Encontre a configuração de Modelo de Fallback Padrão.
3. Selecione seu modelo de fallback global na lista suspensa.
4. Salve a configuração para aplicá-la imediatamente.

Vantagens da configuração global:

• Sem alterações de código: configure uma vez e aplica-se globalmente, sem necessidade de repetir a configuração em cada solicitação.
• Gerenciamento centralizado: gerencie a política de fallback em um único local para ajuste e monitoramento mais fáceis.
• Manutenção simplificada: reduz a complexidade do código e a chance de erros de configuração.
• Substituição flexível: a configuração de fallback no nível da solicitação tem prioridade e pode substituir a configuração global para cenários específicos.

Configuração de fallback no nível da solicitação

Para cenários de negócio específicos, você pode especificar um modelo de fallback em uma solicitação individual para substituir a configuração global.

Especifique o modelo de fallback com o parâmetro router.fallBackModels:

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

Regras de prioridade

Quando várias configurações de fallback estão presentes, a prioridade vai da mais alta para a mais baixa:

1. router.fallBackModels no nível da solicitação: o modelo de fallback especificado em uma solicitação individual.
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.

Administração da conta

Dependendo do tipo de conta, o console pode incluir ativação de modelos no nível da conta, controles de revendedor ou distribuidor, configuração de cobrança e configurações de acesso. Os administradores podem usar esses controles para alinhar o acesso a modelos, a visibilidade de uso e a responsabilidade de cobrança com aplicações, contas de cliente ou unidades de negócio.

Lista de verificação de operações de produção

Cobrança e créditos

O ciyuan_market usa um modelo de cobrança baseado em créditos para cargas de trabalho de texto, imagem, vídeo e outros modelos suportados. Os créditos fornecem uma unidade unificada para uso de múltiplos modelos e múltiplos provedores, permitindo que as equipes gerenciem o consumo de forma consistente entre modalidades e famílias de API.

Os preços detalhados dos modelos estão disponíveis na página de Modelos ou através das APIs de metadados de modelo. O preço pode variar por modelo, provedor, modalidade, resolução, tipo de token, compramento de saída, duração da tarefa, tipo de conta e acordo comercial.

Recarga e carteira

As contas podem adicionar créditos de carteira pré-pagos para uso flexível. Os créditos da carteira são usados após os créditos do plano mensal e dos pacotes de recursos serem consumidos, a menos que uma regra billing rule applies to the account.

Os créditos da carteira não expiram, salvo especificação em contrário nos termos comerciais aplicáveis. Uma taxa de serviço é cobrada ao recarregar a carteira pré-paga.

Planos mensais e pacotes de recursos

Cada usuário ou conta pode selecionar um plano mensal ativo. Os planos mensais fornecem uma quantidade definida de capacidade de uso, termos comerciais e configuração de acesso no nível da conta para o período de cobrança.

Os usuários também podem comprar vários pacotes de recursos para capacidade de uso adicional. Os pacotes de recursos podem separar o uso comprometido do saldo da carteira pré-paga e são úteis para uso de alto volume de texto, imagem, vídeo ou cargas de trabalho dedicadas.

Ordem de dedução

A menos que regras de cobrança personalizadas estejam configuradas, os créditos são deduzidos na seguinte ordem:

Para contas com termos comerciais personalizados, a ordem de dedução, regras de expiração, uso incluído e preços podem ser diferentes. As regras específicas da conta são mostradas no console ou fornecidas através do acordo comercial.

Preços personalizados

Os preços podem ser personalizados para cada usuário ou conta. Clientes corporativos, contas de revendedor, contas de distribuidor e clientes de alto volume podem ser elegíveis para preços personalizados. Entre em contato com as vendas para uma cotação.

Os preços personalizados podem ser configurados por conta, modelo, provedor, modalidade, região, volume de uso ou acordo comercial. Quando os preços personalizados são ativados, o console e as APIs de cobrança refletem os preços e regras de dedução específicos da conta quando disponíveis.

Unidades de preço

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

As unidades de preço podem variar por modelo. Sempre consulte a página de detalhes do modelo ou os metadados de preço antes de ativar um modelo em produção.

Atribuição de uso

O uso do ciyuan_market pode ser revisado por conta, chave API, modelo, modalidade ou intervalo de tempo. Isso permite que as equipes atribuam custos a aplicações, ambientes, clientes ou unidades de negócio internas.

Saldo de créditos

Verifique quantos créditos estão disponíveis em sua conta. O saldo é dividido em três carteiras que são deduzidas em ordem: a allowances do plano mensal, pacotes de recursos comprados e a carteira pré-paga. Um total combinado de recursos (plano mensal + pacotes de recursos, excluindo o pré-pago) também está disponível para rastrear o uso incluído separadamente dos gastos de recarga.

Para recuperar isso programaticamente, consulte GET /v1/billing/balance na Referência da API.

Detalhes de uso

Revise uma lista paginada e cronológica de registros de uso individuais para relatórios, monitoramento e alocação interna de custos. Cada registro mostra o modelo, tipo de modelo (texto, imagem ou vídeo), os créditos deduzidos e um detalhamento de qual carteira cada dedução foi retirada. Os resultados podem ser filtrados por um intervalo de tempo específico.

Para recuperar isso programaticamente, consulte GET /v1/usage na Referência da API.

Histórico de transações

Use o histórico de transações para revisar movimentações de créditos, incluindo recargas, alocações de plano, concessões de pacotes de recursos, deduções de uso, ajustes e correções administrativas.

Para recuperar isso programaticamente, consulte GET /v1/billing/transactions na Referência da API.

Solicitações com falha e reembolsos

Erros de validação, erros de autenticação e erros de permissão geralmente não são cobrados porque nenhuma execução de modelo ocorre. Solicitações que alcançam um modelo upstream ou geram saída parcial podem consumir créditos dependendo do modelo, provedor e estado da resposta.

Para tarefas assíncronas de imagem e vídeo, o comportamento de cobrança depende se a tarefa foi aceita, iniciada, concluída, falhou ou foi cancelada. A resposta de detalhes da tarefa inclui informações de uso quando os créditos foram consumidos.

Recargas, planos mensais, pacotes de recursos e créditos consumidos não são reembolsáveis, a menos que especificado de outra forma no acordo comercial aplicável ou exigido por lei.

Referência da API

Convenções comuns

URL base

Todos os endpoints são servidos sob o prefixo /v1.

Autenticação

Chamadas para endpoints /v1/* usam autenticação por Chave API (não JWT). A Chave API é passada pelo seguinte cabeçalho:

Chaves ausentes ou inválidas retornam 401.

Pré-verificação de saldo

Todos os endpoints de chamada de modelo executam uma pré-verificação de saldo antes da execução:

• Insufficient balance returns Insufficient credit, mapped to:
  • Protocolo OpenAI: HTTP 400, code = insufficient_quota
  • Protocolo Anthropic: HTTP 402, type = billing_error
• Alguns endpoints também estimam um custo mínimo por modelo para uma segunda pré-verificação.

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

Endpoint compatível com OpenAI Chat Completions. Suporta streaming e não streaming, chamadas de ferramentas, modo JSON e 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 resposta (não streaming):

Exemplo de resposta em 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 compatível com OpenAI Responses. Usa input em vez de messages, instructions em vez de uma mensagem de sistema, e um bloco text em vez 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 resposta (não streaming):

O streaming segue os eventos da API Responses:

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

Endpoint compatível com Anthropic Messages. Aceita cabeçalhos x-api-key e anthropic-version: 2023-06-01. Os blocos de conteúdo suportam text, image, tool_use, tool_result, thinking e redacted_thinking.

Exemplos de bloco de imagem:

{ "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 resposta (não streaming):

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

Retorna todos os modelos de API online e ativados.

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}

Retorna um único modelo com o mesmo formato de uma entrada de lista. Retorna HTTP 404 quando o modelo não existe.

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

Resposta de sucesso: um objeto de modelo único com os mesmos campos de uma entrada de lista /v1/models.

Quando o modelo não existe, retorna 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

Consulte as resoluções, proporções e contagens máximas suportadas por um modelo de imagem antes de chamar /v1/image-generations. Não requer autenticação.

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

Consulte os valores de videoType suportados, intervalo de duração, resoluções e proporções para um modelo de vídeo antes de chamar /v1/video-generations. Não requer autenticação.

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

Descrição dos campos de faixas de preço

Os 4 endpoints de consulta de modelos /v1/models, /v1/models/{model}, /v1/image-models e /v1/video-models retornam o preço de faturamento efetivo para o chamador (usuário de API Key), totalmente consistente com a cobrança real, e retornam todas as faixas de preço do modelo.

Diferença de nomenclatura: /v1/models e /v1/models/{model} usam o estilo OpenAI snake_case (price_tiers); /v1/image-models e /v1/video-models usam camelCase (priceTiers). As estruturas são idênticas.

price_tiers / priceTiers é um array; cada elemento é uma faixa de preço:

Os três tipos de modelo compartilham a mesma estrutura; apenas o preenchimento dos campos descritivos difere. Campos não aplicáveis são null:

Significado do preço: os valores inputPrice / outputPrice / cacheReadPrice / cacheWritePrice retornados são os preços unitários de faturamento finais para o usuário de API Key atual após a resolução pela cadeia de preços (chain)→ guidance → preço base, consistentes com a cobrança real. O preço unitário visto pelo chamador varia de acordo com a cadeia de preços à qual pertence (reseller / distributor / empresa / configuração em nível de usuário).

Dedução real = uso ÷ quantity × preço unitário correspondente × ratio. Para vídeo por segundo: dedução real = duration × outputPrice × ratio.

Limites e tratamento de exceções (endpoints somente leitura não retornarão 500 devido a problemas de configuração de preços)

Exemplo de resposta (/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
        }
      ]
    }
  ]
}

Exemplo de resposta (/v1/image-models, modelo de imagem, a estrutura de priceTiers é a mesma, unit é image):

{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "por imagem",
          "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

Envie assincronamente uma tarefa de geração de imagem. Retorna um taskId imediatamente; recupere o resultado fazendo polling de GET /v1/image-generations/{taskId} ou via webhook callbackUrl.

O model, os valores de resolution / ratio suportados, o limite máximo de count e o limite de upload de imagens de referência (fileMax) devem ser obtidos primeiro em GET /v1/image-models. Apenas os valores divulgados na especificação do modelo são aceitos.

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

Respostas de erro:

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

Faça polling de uma tarefa de geração de imagem. status é pending / success / failed. images é um array em string JSON de URLs de imagem; text contém qualquer descrição de texto anexada pelo modelo (ex. saída multimodal do Gemini), null caso contrário.

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 data da resposta:

Tarefa não encontrada:

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

Se callbackUrl foi fornecido no envio, o servidor envia o resultado final success / failed via webhook com o mesmo formato de data.

Exemplo completo (envio + polling)

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

Envie assincronamente uma tarefa de geração de vídeo. Retorna um taskId imediatamente; recupere o resultado fazendo polling de GET /v1/video-generations/{taskId} ou via webhook callbackUrl.

O model, os valores de videoType permitidos, o intervalo de duração (videoDurationMin/Max), resolution / ratio suportados e o limite de upload de ativos de referência (fileMax) devem ser obtidos primeiro em GET /v1/video-models. Apenas códigos de videoType listados em allowedVideoTypes do modelo são aceitos.

Exemplos para cada videoType:

1. Texto para vídeo (videoType=1)

Gere um vídeo apenas a partir de um prompt de texto; não são necessários ativos de referência.

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. Imagem para vídeo - primeiro quadro (videoType=2)

Forneça um único quadro inicial em imageUrls; o modelo gera um vídeo a partir desse quadro.

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. Imagem para vídeo - primeiro e último quadro (videoType=3)

Forneça o primeiro e o último quadro em imageUrls (ordem: [primeiro, último]); o modelo gera um vídeo de transição entre os dois quadros.

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. Imagem para vídeo - referência (videoType=4)

Forneça uma ou mais imagens de referência em imageUrls; o modelo usa o estilo/conteúdo delas como referência (não como um primeiro/último quadro forçado) para gerar o vídeo.

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. Todas as referências (videoType=5)

Referências mistas de imagem / vídeo / áudio. Faça referência aos ativos por posição no prompt: a 1ª entrada em imageUrls é @图片 1, a 1ª em videoUrls é @视频 1, a 1ª em audioUrls é @音频 1. videoUrls também aceita strings 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
  }'

Resposta de envio (todos os cinco tipos):

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

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

Faça polling de uma tarefa de geração de vídeo. status é pending / success / failed; videoUrl é a URL do vídeo gerado e lastFrameUrl é a URL do último quadro (cenários de imagem-para-vídeo).

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 data da resposta:

Se callbackUrl foi fornecido no envio, o servidor envia o resultado final via webhook com o mesmo formato de data.

Exemplo completo (envio + polling)

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

Retorna o saldo da conta dividido em três carteiras: plano mensal, pacotes de recursos e crédito pré-pago.

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 resposta:

Campos de WalletDetailVO:

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

Detalhes de cobrança paginados de chamadas de modelo, com snapshot por preço (priceSnapshotId), ordenados por tempo de criação do pedido em ordem decrescente. Apenas registros de cobrança normal (reason = model usage) são retornados.

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"

Wrapper de resposta:

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

Campos de UsageDetailVO:

Campos de CreditDetailItem:

Convenção de valor nulo: apenas os campos relevantes para cada modelType são preenchidos; o restante é null. text preenche os campos de token; image preenche imageCount/imageResolution/imageRatio; video preenche videoResolution/videoRatio/videoDurationSec.

Exemplo de resposta:

{
  "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 das transações de recarga pagas (status=2) do usuário atual, ordenadas por created_at em ordem decrescente.

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"

Wrapper de resposta:

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

Operacional

Erros

O ciyuan_market retorna códigos de erro estáveis para que as aplicações possam lidar com repetições, fallbacks, problemas de cobrança e depuração de forma consistente.

Endpoints compatíveis com provedores tentam preservar o formato de erro da família de API original quando possível. Endpoints nativos do ciyuan_market usam o objeto de erro do ciyuan_market.

Mapeamento de status HTTP e códigos de erro

Códigos de erro comuns

Recursos

• 🤖 Chat multi-API: suporta os endpoints compatíveis com OpenAI Chat Completions, Anthropic Messages e OpenAI Responses
• 🖼️ Geração multimodal: além do chat de texto, suporta tarefas assíncronas de geração de imagem e vídeo (texto-para-, imagem-para-, primeiro/último quadro, ativo de referência)
• 🔍 Consulta de modelos e conta: lista modelos disponíveis, detalhes de modelos, saldo da conta, detalhes de uso/cobrança e transações de recarga
• 🔑 Chave passada via cabeçalho: cada chamada lê a chave da API a partir do cabeçalho da requisição, então uma única implantação pode ser compartilhada por várias contas — o servidor nunca persiste nem armazena em cache qualquer chave

Início rápido

Use no Claude Code (recomendado). Adicione -s user para registrá-lo no escopo do usuário (disponível em todos os seus projetos).

Passo 1: Adicionar a conexão

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

Passo 2: Verificar a conexão

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

Passo 3: Comece a usar

Você pode pedir ao Claude coisas como:

• "Use o ciyuan_market para chamar o claude-sonnet-5 e escrever um poema sobre o outono"
• "Liste os modelos disponíveis na minha conta ciyuan_market"
• "Verifique meu saldo e uso recente no ciyuan_market"
• "Use o ciyuan_market para gerar uma imagem de uma cidade cyberpunk à noite"

O Claude chamará automaticamente a ferramenta MCP correspondente e retornará o resultado.

Usando com o Claude Desktop

Adicione isto à seção mcpServers:

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

Usando com o Codex CLI

Recomendado: use env_http_headers para ler a chave a partir de uma variável de ambiente

Primeiro, exporte a variável de ambiente no seu shell:

export CIYUAN_MARKET_API_KEY=<sua chave de API do ciyuan_market>

Depois, em ~/.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 escrever a chave diretamente na configuração (útil se você não quiser gerenciar uma variável de ambiente separada, mas note que a chave fica então armazenada em texto simples no arquivo de configuração):

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

Se estiver adicionando pela interface de configurações do Codex:

• Tipo: HTTP / Streamable HTTP
• Nome: ciyuanmarket
• URL: https://api.ciyuan-market.com/mcp
• Nome do cabeçalho: X-Ciyuanmarket-Api-Key
• Valor do cabeçalho: sua chave de API do ciyuan_market

Verificar a conexão

Depois de iniciar o Codex CLI, o comando /mcp lista os servidores MCP configurados e o status de suas conexões — basta confirmar que carregou corretamente. O padrão de uso é igual ao do Claude: o Codex escolhe automaticamente a ferramenta certa.

Se o seu arquivo de configuração já tiver outros servidores MCP, adicione este no mesmo nível. Saia completamente e reabra o Claude Desktop após editar.

Ferramentas

Este servidor MCP fornece 14 ferramentas, agrupadas em cinco categorias:

1. Chat

1. chat_completion — Chat Completions

Envia uma única requisição de chat e retorna a resposta completa do modelo (sem streaming). Além de texto simples, também aceita imagens para compreensão visual (o modelo deve suportar vision) — mude o content da mensagem de string para um array de blocos de conteúdo misturando text e image_url.

Entrada multimodal (text / image / video)

Entrada de imagem (URL):

{"role": "user", "content": [
  {"type": "text", "text": "O que há nesta imagem?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Entrada de imagem (Base64):

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

Formatos suportados: PNG, JPEG, GIF (apenas o primeiro quadro), WebP. Limite de tamanho por imagem 20MB.

Nota: imagens grandes em Base64 produzem strings muito longas e podem falhar pelo corpo da requisição exceder o limite; prefira passar imagens por URL.

O parâmetro detail (opcional, definido no objeto image_url) controla a fidelidade do processamento da imagem: "auto" (padrão — o modelo decide pelo tamanho) / "low" (miniatura 512x512, rápido e barato, bom para classificação simples) / "high" (resolução total, bom para texto pequeno / detalhes). O array content de uma mensagem pode conter vários blocos image_url para passar várias imagens.

Video input (URL):

{"role": "user", "content": [
  {"type": "text", "text": "Descreva o que acontece neste vídeo."},
  {"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>"}}

Modelos com suporte a entrada de vídeo no ciyuan_market incluem alguns modelos das séries Qwen, Doubao (dola-seed), Kimi, MiniMax — verifique input_modalities retornado por list_models. O padrão oficial Chat Completions da OpenAI não suporta vídeo nativamente, mas o gateway ciyuan_market suporta via

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

formato de extensão. Este formato é consistente com o formato video_url usado por OpenRouter, NVIDIA NIM, vLLM e outras plataformas.

2. create_message — Compatível com Anthropic Messages

Chama o endpoint compatível com Anthropic Messages (sem streaming). Os blocos de conteúdo suportam text, image, tool_use, tool_result, thinking, redacted_thinking. As imagens são passadas via blocos de conteúdo

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

.

Entrada multimodal (text / image / video)

A entrada de imagem suporta três tipos de source:

1. Codificação Base64 (atenção: o campo data é uma string Base64 pura, sem o prefixo data:); media_type suporta image/jpeg, image/png, image/gif, image/webp:

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

2. Referência por URL:

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

3. File ID (primeiro faça upload da imagem via Files API com purpose="vision" para obter um file_id):

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

O array content de uma mensagem pode conter vários blocos image para passar várias imagens.

Nota: imagens grandes em Base64 produzem strings muito longas e podem falhar pelo corpo da requisição exceder o limite; prefira passar imagens por URL.

Entrada de vídeo: a API Anthropic Messages não suporta arquivos de vídeo nativamente. Para compreensão de vídeo, primeiro extraia quadros-chave com ffmpeg ou similar, depois passe cada quadro como um bloco de conteúdo image. Alguns gateways compatíveis podem estender o suporte a

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

e similares — consulte a documentação do seu gateway. 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 — Compatível com OpenAI Responses

Usa input em vez de messages, instructions em vez de mensagem de sistema e text.format em vez de response_format. Além de texto simples, também aceita imagens para compreensão visual (o modelo deve suportar vision) — defina input como um array de objetos de mensagem cujo content é um array de blocos de conteúdo misturando texto e imagens.

Entrada multimodal (text / image / video)

Nota: a Responses API usa os tipos de bloco de conteúdo input_text / input_image / input_video (não text / image_url / video_url do Chat Completions), e image_url / video_url é uma string direta, não um objeto aninhado.

Entrada de imagem (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "O que há nesta imagem?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Entrada de imagem (Base64):

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

Formatos suportados: PNG, JPEG, GIF (apenas o primeiro quadro), WebP. Limite de tamanho por imagem 20MB.

Nota: imagens grandes em Base64 produzem strings muito longas e podem falhar pelo corpo da requisição exceder o limite; prefira passar imagens por URL.

Entrada de imagem (File ID):

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

o file_id é obtido fazendo upload da imagem via Files API com purpose="vision".

O parâmetro detail (opcional, no objeto input_image) controla a fidelidade do processamento: "auto" (padrão) / "low" (miniatura 512x512, rápido e barato) / "high" (resolução total, para texto pequeno / detalhes) / "original" (resolução original). O array content de uma mensagem pode conter vários blocos input_image para várias imagens.

Video input (URL):

[{"role": "user", "content": [
  {"type": "input_text", "text": "Descreva o que acontece neste vídeo."},
  {"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>"}

Modelos com suporte a entrada de vídeo no ciyuan_market incluem alguns modelos das séries Qwen, Doubao (dola-seed), Kimi, MiniMax — verifique input_modalities retornado por list_models. O padrão oficial Responses API da OpenAI não suporta vídeo nativamente, mas o gateway ciyuan_market suporta via

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

formato de extensão. Este formato é consistente com o formato input_video usado por BytePlus/Volcengine e outras plataformas.

2. Modelos e conta

4. list_models — Listar modelos disponíveis

Retorna os modelos disponíveis para a conta atual, com metadados de fornecedor, modalidade, capacidade e preço. Sem parâmetros. Cada item da lista inclui uma faixa de preço price_tiers — o preço de cobrança efetivo do chamador, correspondendo ao débito real (veja Referência do campo de faixas de preço) (only some newer models).

5. get_model — Obter detalhes de um modelo

A resposta inclui uma faixa de preço price_tiers (veja Referência do campo de faixas de preço); retorna 404 (sem campos de preço) quando o modelo não existe.

6. get_balance — Verificar saldo da conta

Retorna o uso e o saldo da conta atual. Sem parâmetros.

3. Cobrança

7. list_usage — Detalhes de uso/cobrança de modelos

Detalhes paginados de cobrança por uso de modelos, ordenados pela data de criação do pedido em ordem decrescente. Apenas cobranças normais de uso — sem recargas ou ajustes.

8. list_transactions — Transações de recarga/pacote

Transações pagas de recarga / compra de pacote, paginadas e ordenadas pela data de criação em ordem decrescente.

4. Geração de imagens

9. list_image_models — Listar modelos de imagem

Retorna os modelos de geração de imagem suportados, com resolução, proporção de tela, número máximo de imagens (maxCount) e número máximo de imagens de referência (fileMax). Sem parâmetros. Verifique isso antes de gerar imagens — você só pode passar valores que ele publica. Cada item da lista inclui uma faixa de preço priceTiers (veja Referência do campo de faixas de preço).

10. create_image_generation — Enviar uma tarefa de geração de imagem

Envia de forma assíncrona e retorna imediatamente um taskId; consome crédito da conta.

11. get_image_generation — Consultar uma tarefa de imagem

Retorna: status é pending / success / failed; images é um array de string JSON com URLs de imagens; text traz qualquer saída extra do modelo (ex.: saída multimodal do Gemini).

5. Geração de vídeos

12. list_video_models — Listar modelos de vídeo

Retorna os modelos de geração de vídeo suportados, com allowedVideoTypes, faixa de duração (videoDurationMin/Max), resolução, proporção de tela e limite de ativos de referência (fileMax). Sem parâmetros. Verifique isso antes de gerar vídeo. Cada item da lista inclui uma faixa de preço priceTiers (veja Referência do campo de faixas de preço).

13. create_video_generation — Enviar uma tarefa de geração de vídeo

Envia de forma assíncrona e retorna imediatamente um taskId; consome crédito da conta.

Significado de video_type:

14. get_video_generation — Consultar uma tarefa de vídeo

Referência do campo de faixas de preço

As saídas destas 4 ferramentas de consulta de modelos — list_models, get_model, list_image_models, list_video_models — retornam o preço de cobrança efetivo do chamador (usuário do API Key), correspondendo exatamente ao débito real, e incluem todas as faixas de preço do modelo.

Diferença de nomenclatura: list_models / get_model seguem o snake_case do OpenAI (price_tiers); list_image_models / list_video_models seguem camelCase (priceTiers). A estrutura é a mesma.

price_tiers / priceTiers é um array; cada elemento é uma faixa de preço:

Os três tipos de modelo compartilham a mesma estrutura; apenas os campos de descrição diferem, e campos não aplicáveis são null:

Significado do preço: os inputPrice / outputPrice / cacheReadPrice / cacheWritePrice retornados, etc., são os preços unitários finais de cobrança para o usuário atual do API Key, resolvidos através da cadeia de preço (chain) → guidance → preço base, e correspondem ao débito real. O preço unitário que o chamador vê varia conforme sua cadeia de preço (reseller / distributor / empresa / configuração de nível de usuário).

Débito real = uso ÷ quantity × preço unitário × ratio. Para cobrança de vídeo por segundo: débito real = duration × outputPrice × ratio.

Casos extremos e tratamento de erros (um endpoint somente leitura nunca retorna 500 por configuração de preço):

Exemplo de resposta (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
        }
      ]
    }
  ]
}

Exemplo de resposta (list_image_models, modelo de imagem; priceTiers mesma estrutura, unit é image):

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

Exemplos

Exemplo 1: uma requisição de chat simples

Pergunte: "Use o ciyuan_market para chamar o claude-sonnet-5 e perguntar o que é o GIL do Python"

A IA chamará chat_completion com:

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

Exemplo 2: uso de ferramentas via o endpoint Anthropic Messages

Pergunte: "Use o endpoint Messages do ciyuan_market e deixe o modelo decidir se deve verificar o clima"

A IA chamará create_message, passando uma definição de tools e tool_choice; a resposta incluirá um bloco de conteúdo tool_use.

Exemplo 3: listar modelos disponíveis

Pergunte: "Liste os modelos na minha conta ciyuan_market"

A IA chamará list_models, retornando IDs, fornecedores, modalidades, preços e mais para cada modelo disponível.

Exemplo 4: verificar saldo e uso

Pergunte: "Verifique meu uso do ciyuan_market neste mês"

A IA chamará get_balance para o saldo e, em seguida, list_usage (com start_time delimitado a este mês) para o detalhamento de uso.

Exemplo 5: gerar uma imagem

Pergunte: "Use o ciyuan_market para gerar uma imagem de uma cidade cyberpunk à noite"

A IA primeiro chamará list_image_models para verificar as especificações, depois create_image_generation para obter um taskId, e então fará polling em get_image_generation para obter a URL da imagem.

Exemplo 6: texto para vídeo

Pergunte: "Use o ciyuan_market para gerar um vídeo de 5 segundos de uma nebulosa espacial"

A IA primeiro chamará list_video_models para verificar as especificações, depois create_video_generation (video_type=1, duration=5), e após obter um taskId, fará polling em get_video_generation.

FAQ

A chamada de ferramenta falha com "missing ciyuan_market API Key"

• Você executou claude mcp add sem --header, ou a chave está errada
• Se estiver editando o JSON de configuração diretamente, o nome do campo headers está errado (deveria ser X-Ciyuanmarket-Api-Key)
• Executando localmente sem a variável de ambiente CIYUAN_MARKET_API_KEY definida

A chamada de ferramenta falha com "ciyuan_market returned 401 unauthorized"

A própria chave de API está errada ou expirou — gere uma nova no console do ciyuan_market.

O Claude não está chamando as ferramentas do ciyuan_market — o que fazer?

• Confirme que a conexão mostra ✓ Connected via claude mcp list
• Verifique o status da conexão: claude mcp get ciyuanmarket
• Tente ser explícito: "Use a ferramenta chat_completion do ciyuan_market para chamar claude-sonnet-5 …"

A geração de imagem/vídeo fica pendente para sempre

• Faça polling de tarefas de imagem com get_image_generation e de tarefas de vídeo com get_video_generation — note que o status de uma tarefa de vídeo em execução é "running", não "pending"
• A geração leva tempo, geralmente de alguns a dezenas de segundos, mais para vídeo
• Se você passou um callback_url, a tarefa fará o callback na conclusão — sem necessidade de polling

Erros em list_image_models / list_video_models

Nenhuma das duas ferramentas consome crédito por si só — um erro geralmente indica um problema de chave ou de rede. Primeiro confirme que list_models funciona normalmente.

Notas

• Nome do cabeçalho:O MCP passa a chave via X-Ciyuanmarket-Api-Key.
• Consumo de crédito:chat_completion / create_message / create_response / create_image_generation / create_video_generation consomem todos crédito da conta — verifique get_balance primeiro se quiser saber o saldo antecipadamente.
• Verifique as especificações antes de gerar:Parâmetros de geração de imagem/vídeo como model, resolution, ratio, count, duration e video_type devem usar apenas valores publicados por list_image_models / list_video_models, caso contrário a chamada resulta em erro.
• Sem streaming:Nenhum dos três endpoints de chat suporta streaming — cada um retorna o resultado completo de uma vez.
• Design sem estado:Cada requisição é independente e nenhuma sessão é armazenada; para conversas de múltiplos turnos, use previous_response_id de create_response ou mantenha o histórico você mesmo em messages.