Messages

POST https://api.tokentosea.com/v1/messages

按 Anthropic Messages 协议发送对话。TokenToSea 把请求转发到各厂商官方的 Anthropic 兼容接口，原样返回 Message 对象，并按实际用量结算。

前提：全能密钥或模型密钥，账户可用余额足以覆盖本次预留。Python 示例需要 pip install anthropic，Node.js 示例需要 Node.js 18+ 与 npm install @anthropic-ai/sdk。

支持的型号#

截至 2026-10-21，97 个型号开放本接口：千问 56、智谱 17、豆包 8、MiniMax 6、Kimi 4、阶跃星辰 4、DeepSeek 2。以 GET /v1/models 中 verified_endpoints 包含 /v1/messages 的型号为准。

qwen-plus-character 与 glm-4.7-flash 在本接口只支持非流式（JSON）响应；其余开放的型号两种方式都支持。

请求头#

请求头	必填	说明
`x-api-key` 或 `Authorization`	必填	密钥。Anthropic SDK 默认发送 `x-api-key`，网关两种都接受
`Content-Type`	必填	`application/json`
`Idempotency-Key`	建议	见幂等
`anthropic-version`	可选	可以发送，但不会被使用：网关始终以 `2023-06-01` 调用厂商

请求体#

参数	类型	必填	说明
`model`	string	必填	型号 ID
`max_tokens`	integer	必填	输出上限，Anthropic 协议要求必须提供，不能超过型号的 `max_output_tokens`
`messages`	array	必填	`role` 为 `user` / `assistant`，`content` 为字符串或内容块数组
`system`	string \| array	可选	系统提示
`stream`	boolean	可选	`true` 时以 SSE 事件返回
`tools`	array	可选	自定义工具：需要 `name` 与 `input_schema`；或 `type` 为 `custom`。服务端工具（联网搜索、代码执行等带其他 `type` 的工具）返回 `422 hosted_tools_not_priced`
`tool_choice`	object	可选	原样转发
`thinking`	object	可选	思考配置，原样转发；`type` 是否为 `disabled` 会用于匹配计价规则
其他字段	—	可选	`temperature`、`top_p`、`top_k`、`stop_sequences`、`metadata` 等原样转发，是否支持以厂商为准

内容块#

内容块	写法	说明
文本	`{ "type": "text", "text": "…" }`	全部型号
图片	`{ "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "…" } }` 或 `source: { "type": "url", "url": "https://…" }`	仅已验收图片输入的型号，否则 `422 input_modality_not_verified`
工具结果	`{ "type": "tool_result", "tool_use_id": "…", "content": "…" }`	回传工具执行结果
文档	`{ "type": "document", … }`	当前没有型号在本接口开放文档输入

显式缓存#

cache_control: { "type": "ephemeral" } 可写在 system、messages、tools 的内容块上，只对已定价显式缓存的型号开放：千问 3.5–3.8 等支持缓存的型号、MiniMax M2.5 / M2.7 系列（显式缓存仅在本接口可用）、kimi-k3。千问每次最多 4 个断点；ttl 只能是 5m（kimi-k3 另可 1h）。其他情况返回 422 explicit_cache_not_priced、cache_breakpoint_limit 或 cache_ttl_not_priced。

不支持的字段#

mcp_servers、container、context_management 返回 422 auxiliary_product_not_priced；服务端工具返回 422 hosted_tools_not_priced；prompt_cache_options 在本接口不可用（422 cache_options_not_priced）。

响应#

响应示例

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "glm-5.3",
  "content": [{ "type": "text", "text": "我可以帮你写作、翻译、总结和编程。" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 20, "output_tokens": 18 }
}

字段以厂商返回为准。结算依据 usage 中的 input_tokens、output_tokens 以及缓存读写 token。结算未完成时返回 202 和结果信封。

流式事件#

"stream": true 时按 Anthropic 事件格式返回：message_start、content_block_start、content_block_delta、content_block_stop、message_delta（含 usage）、message_stop。

message_stop 在主站完成结算后才发出。
结算失败时以 event: error、data: {"error":{"code":"execution_result_pending"}} 结束；Anthropic SDK 会把它抛出为错误。用同一个键查询 /v1/results/{key}。

示例#

基础对话#

Anthropic SDK 的地址填 https://api.tokentosea.com（不带 /v1），SDK 会自行拼接 /v1/messages。

curl https://api.tokentosea.com/v1/messages \
  -H "x-api-key: $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "glm-5.3",
    "max_tokens": 1024,
    "system": "你是一名简洁的助手。",
    "messages": [{"role": "user", "content": "请简短介绍一下你能帮助我完成什么。"}]
  }'

import os
import uuid

import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["TOKENTOSEA_API_KEY"],
    base_url="https://api.tokentosea.com",
    max_retries=0,
)
message = client.messages.create(
    model="glm-5.3",
    max_tokens=1024,
    system="你是一名简洁的助手。",
    messages=[{"role": "user", "content": "请简短介绍一下你能帮助我完成什么。"}],
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)
print(message.content[0].text)
print(message.usage)

import Anthropic from '@anthropic-ai/sdk';
import { randomUUID } from 'node:crypto';

const client = new Anthropic({
  apiKey: process.env.TOKENTOSEA_API_KEY,
  baseURL: 'https://api.tokentosea.com',
  maxRetries: 0,
});
const message = await client.messages.create(
  {
    model: 'glm-5.3',
    max_tokens: 1024,
    system: '你是一名简洁的助手。',
    messages: [{ role: 'user', content: '请简短介绍一下你能帮助我完成什么。' }],
  },
  { headers: { 'Idempotency-Key': randomUUID() } },
);
console.log(message.content[0].text);
console.log(message.usage);

流式输出#

curl -N https://api.tokentosea.com/v1/messages \
  -H "x-api-key: $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "glm-5.3",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "用三句话解释什么是向量检索。"}]
  }'

import os
import uuid

import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["TOKENTOSEA_API_KEY"],
    base_url="https://api.tokentosea.com",
    max_retries=0,
)
with client.messages.stream(
    model="glm-5.3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用三句话解释什么是向量检索。"}],
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print("\n", stream.get_final_message().usage)

import Anthropic from '@anthropic-ai/sdk';
import { randomUUID } from 'node:crypto';

const client = new Anthropic({
  apiKey: process.env.TOKENTOSEA_API_KEY,
  baseURL: 'https://api.tokentosea.com',
  maxRetries: 0,
});
const stream = await client.messages.create(
  {
    model: 'glm-5.3',
    max_tokens: 1024,
    stream: true,
    messages: [{ role: 'user', content: '用三句话解释什么是向量检索。' }],
  },
  { headers: { 'Idempotency-Key': randomUUID() } },
);
for await (const event of stream) {
  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') process.stdout.write(event.delta.text);
  if (event.type === 'message_delta') console.log('\n', event.usage);
}

图片输入#

qwen3.8-max 在本接口已验收图片输入。

curl https://api.tokentosea.com/v1/messages \
  -H "x-api-key: $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "qwen3.8-max",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image", "source": {"type": "url", "url": "https://example.com/photo.jpg"}},
        {"type": "text", "text": "这张图片里有什么？"}
      ]
    }]
  }'

import base64
import os
import uuid
from pathlib import Path

import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["TOKENTOSEA_API_KEY"],
    base_url="https://api.tokentosea.com",
    max_retries=0,
)
image_data = base64.b64encode(Path("photo.png").read_bytes()).decode()

message = client.messages.create(
    model="qwen3.8-max",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}},
            {"type": "text", "text": "这张图片里有什么？"},
        ],
    }],
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)
print(message.content[0].text)

import Anthropic from '@anthropic-ai/sdk';
import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const client = new Anthropic({
  apiKey: process.env.TOKENTOSEA_API_KEY,
  baseURL: 'https://api.tokentosea.com',
  maxRetries: 0,
});
const imageData = (await readFile('photo.png')).toString('base64');

const message = await client.messages.create(
  {
    model: 'qwen3.8-max',
    max_tokens: 1024,
    messages: [{
      role: 'user',
      content: [
        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: imageData } },
        { type: 'text', text: '这张图片里有什么？' },
      ],
    }],
  },
  { headers: { 'Idempotency-Key': randomUUID() } },
);
console.log(message.content[0].text);

错误#

状态码	`code`	原因与处理
`422`	`endpoint_not_verified`	该型号未开放 Messages，改用 Chat Completions
`422`	`response_mode_not_verified`	型号未开放所选响应方式
`422`	`hosted_tools_not_priced`	使用了服务端工具，或自定义工具缺少 `name` / `input_schema`
`422`	`auxiliary_product_not_priced`	使用了 `mcp_servers`、`container` 或 `context_management`
`422`	`explicit_cache_not_priced`、`cache_breakpoint_limit`、`cache_ttl_not_priced`	见显式缓存
`400` / `409`	`main_wallet_authorization_failed`	见 API 概览

MessagesPOST