文本生成

每个文本模型都可以通过三个端点调用。选你的代码或 SDK 已经在用的那一个；模型、价格和回答都一样。

端点	请求格式	适用场景
/v1/chat/completions	OpenAI Chat Completions	大多数 SDK、框架和工具。默认选它。
/v1/responses	OpenAI Responses	你的代码已经在用 Responses API。
/v1/messages	Anthropic Messages	你的代码用 Anthropic SDK，或用 Claude Code 这类工具。适用于所有对话模型，不只是 Claude。

本页的完整程序都是真实的文件，发布前我们都会实际运行一遍。设置好 OCEANTOKEN_API_KEY，即可原样运行。

Chat completions

# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1"),
    api_key=os.environ["OCEANTOKEN_API_KEY"],
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
print(response.choices[0].message.content)

一段对话就是 messages 里的列表，按时间先后排列：可选的一条 system 消息写你的指令，然后是 user 和 assistant 轮流发言。API 不在请求之间保存任何内容，所以每次都要发送完整的对话，并把模型上一次的回答作为 assistant 消息加进去。

messages = [
    {"role": "system", "content": "你是一个回答简洁的旅行助手。"},
    {"role": "user", "content": "在波尔图待两天，该看什么？"},
    {"role": "assistant", "content": "里贝拉老城、莱罗书店、加亚新城的波特酒窖……"},
    {"role": "user", "content": "下雨天去哪个最合适？"},
]

回答在 choices[0].message.content 里。finish_reason 说明为什么停止：stop 表示回答完整，length 表示达到了 max_tokens，tool_calls 表示模型想要调用工具。

流式输出回答

设置 stream，边生成边读取回答：

# Streaming: tokens arrive as they are generated. Use this for anything a person
# is waiting on, and for long answers, which would otherwise hit the request timeout.
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1"),
    api_key=os.environ["OCEANTOKEN_API_KEY"],
)

with client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "Count from one to five, one number per line."}],
    stream=True,
) as stream:
    for chunk in stream:
        delta = chunk.choices[0].delta.content if chunk.choices else None
        if delta:
            print(delta, end="", flush=True)
print()

只要有人在等结果，或者回答很长，就用流式输出：非流式请求超过 240 秒会被关闭。要在 chat completions 流的末尾拿到 token 数，请发送 "stream_options": {"include_usage": true}。事件格式和流式输出中的错误见 API 参考 → 流式输出。

Responses API

# pip install openai
# The Responses API takes the same models as chat completions.
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1"),
    api_key=os.environ["OCEANTOKEN_API_KEY"],
)

response = client.responses.create(
    model="openai/gpt-5-mini",
    instructions="Answer in one short sentence.",
    input="Why is the sea salty?",
)
print(response.output_text)

output_text 就是回答。设置 stream=True 可流式输出，流以 response.completed 事件结束。

Anthropic Messages API

# pip install anthropic
# Claude models are served on /v1/messages. The Anthropic SDK works unchanged:
# give it the OceanToken host and your OceanToken key. It adds /v1 itself, so it
# takes the base URL without the /v1 that OpenAI SDKs need.
import os
import anthropic

client = anthropic.Anthropic(
    base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1").removesuffix("/v1"),
    api_key=os.environ["OCEANTOKEN_API_KEY"],
)

message = client.messages.create(
    model="anthropic/claude-haiku-4.5",
    max_tokens=64,
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
print(message.content[0].text)

Anthropic SDK 要填 https://api.oceantoken.ai，不带 /v1，它会自己加上。改 model，同样的代码就能调用 GPT、Gemini、DeepSeek 或其他任何对话模型。

参数

各格式的常用参数都可以用：max_tokens、temperature、top_p、stop、n、seed、tools、tool_choice、response_format 等。需要注意几点：

• 模型不支持的参数会被丢弃，请求在没有它的情况下照常运行。所以响应成功并不能证明参数生效了，见使用哪种 API 格式。
• max_tokens 超过模型自身的输出上限时，会被调低到这个上限，而不是报错。上限写在模型页面的 Max output 一行。
• 模型页面（见模型）的 Capabilities 一行列出它支持的能力：工具调用（tool calling）、图片输入（image input）、推理（reasoning）、联网搜索（web search）。

推理

页面上标有 reasoning 的模型会先思考再回答。在 chat completions 上，reasoning_effort 设置思考的程度：low、medium 或 high。程度越高，输出 token 越多，费用越高、回答越慢。

response = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[{"role": "user", "content": "1001 是质数吗？只回答是或否。"}],
    reasoning_effort="low",
)

推理 token 按输出计费。会返回推理过程的模型，把它放在 choices[0].message.reasoning_content 里，回答仍在 content 里。两者都要留出空间：max_tokens 太小时，可能在写出回答之前就被推理用完。

结构化输出

要拿到符合某个 schema 的 JSON，把 schema 放在 response_format 里发送：

# pip install openai
# Structured output: the answer is JSON that matches your schema.
import json
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("OCEANTOKEN_BASE_URL", "https://api.oceantoken.ai/v1"),
    api_key=os.environ["OCEANTOKEN_API_KEY"],
)

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "date": {"type": "string", "description": "YYYY-MM-DD"},
        "attendees": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["name", "date", "attendees"],
    "additionalProperties": False,
}

response = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[{"role": "user", "content": "Alice and Bob are going to a science fair on 2026-11-14."}],
    response_format={"type": "json_schema", "json_schema": {"name": "event", "schema": schema, "strict": True}},
)
event = json.loads(response.choices[0].message.content)
print(event["name"], event["date"], event["attendees"])

{"type": "json_object"} 只要求返回合法的 JSON，不指定 schema。并非所有模型都遵守 schema：不支持的模型会丢弃 response_format，用普通文字回答。所以请解析回答并处理失败的情况，并用你要用的模型先测试一遍。

让 OceanToken 选模型

smart-router 是一个模型名称，它会为每个请求挑选一个文本模型。请求按实际回答的模型的价格计费，不额外加价。响应中的 model 字段和 x-oceantoken-model 响应头会写明是哪个模型。

费用

非流式响应在 x-oceantoken-cost 响应头中带上费用。流式响应可以事后按响应的 id 查询，见请求的费用。重复出现的长提示（比如指令或文档）可以用提示缓存降低费用。

下一步

• 工具调用：让模型调用你的函数。
• 图片输入：随问题一起发送图片。
• 错误与重试与故障转移：哪些该重试，哪些不该。
• 所有模型的价格见 oceantoken.ai 的模型页面。