OpenAI 兼容聊天

使用 POST /v1/chat/completions 和 GET /v1/models，更换 base URL 与 API Key 即可通过 OpenAI Python 或 JavaScript SDK 调用。这是文本 Chat Completions 格式兼容，不代表支持 OpenAI 的所有接口和能力。

鉴权与模型

使用控制台现有密钥：Authorization: Bearer sk-your-key。模型列表仅包含当前可用的文本模型和公开 ID。请求应使用返回的 id，不能使用显示名称。价格与音色仍通过 /v1/chat/catalog 获取。

curl https://api.coldstart.win/v1/models -H "Authorization: Bearer sk-your-key"

{"object":"list","data":[{"id":"chat-standard","object":"model","created":0,"owned_by":"girllab"}]}

请求与多轮历史

每次请求按顺序传入完整 messages 数组，支持 system、developer、user、assistant、tool 角色。内容可为字符串或 { "type": "text", "text": "..." } 数组。服务端不会额外叠加历史或默认人设。 每轮都应携带所需系统指令和相关历史。

curl https://api.coldstart.win/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"chat-standard","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}],"max_tokens":256}'

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1792540800,
  "model": "chat-standard",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!", "refusal": null}, "logprobs": null, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
}

支持的参数

必填 model、非空 messages 数组。可选：stream（默认 false）、temperature（0–2）、top_p（0–1）、max_tokens 或 max_completion_tokens（整数 1–8192，二选一）、stop（一个字符串或 1–4 个字符串）、presence_penalty 和 frequency_penalty（−2–2）、seed（安全整数）、n（仅 1）。未传生成参数时采用服务默认值；采样参数效果取决于所选模型。stream_options: {"include_usage": true} 只能配合 stream: true。可选字段传 null 时使用默认值。HTTP JSON 请求体上限为 15 MiB，模型上下文仍受其 token 容量限制。

流式与用量

流式采用仅含 data: 的 SSE，不使用自定义 event: delta 或 event: completed。读取 choices[0].delta.content，结束时读取 finish_reason（stop、length 或 content_filter, tool_calls）及 data: [DONE]。启用 include_usage: true 后，在 [DONE] 前追加 choices: []、包含最终 usage 的数据块，其他块的 usage 为 null；未启用时不输出流式 usage 字段。同一请求的所有块使用相同的本地生成 ID、创建时间与公开模型 ID。

{"model":"chat-standard","messages":[{"role":"user","content":"Hello!"}],"stream":true,"stream_options":{"include_usage":true}}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[{"index":0,"delta":{"content":"Hello!"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}

data: [DONE]

错误与支持范围

错误格式为 { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } }。HTTP 400 表示无效或暂不支持的参数；401 为密钥无效，402 为积分不足，429 为限流，503 为服务暂不可用，504 为超时。报错统一脱敏。开始流式前返回 HTTP JSON 错误；开始后以 data: {"error": ...} 结束，不发送成功结束标记。不能把部分文本当作完整成功。首段文本等待上限 90 秒，文本增量空闲上限 60 秒，每次增量重置；非流式请求超时为 60 秒。

暂不支持图片／音频输入、托管搜索、托管代码执行、旧版 functions / function_call、自定义工具类型、logprobs、多个候选、store、Responses API 和其他未列出的参数，会明确拒绝而非静默忽略。语音使用 /v1/chat/speech。

计费与 SDK 示例

沿用相同余额、公开模型价格和输入／输出 token 计费。调用前预留积分，成功后按实际用量结算并释放剩余预留；生成失败、用量无效或结算前断连释放预留。结算成功后取消连接不会撤销扣费。调用进入 Usage history 和后台仪表盘；标准 JSON 包含 usage，不额外返回自定义 billing。重复发送可能再次计费，本接口不提供幂等保证。

pip install openai
npm install openai

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["KARMAN_API_KEY"], base_url="https://api.coldstart.win/v1", max_retries=0)
print([model.id for model in client.models.list().data])
model = os.environ["KARMAN_MODEL"]
messages = [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}]
reply = client.chat.completions.create(model=model, messages=messages, max_tokens=256)
print(reply.choices[0].message.content)

stream = client.chat.completions.create(model=model, messages=messages, max_tokens=256,
    stream=True, stream_options={"include_usage": True})
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.KARMAN_API_KEY, baseURL: "https://api.coldstart.win/v1", maxRetries: 0 });
const models = await client.models.list();
console.log(models.data.map(model => model.id));
const stream = await client.chat.completions.create({
  model: process.env.KARMAN_MODEL,
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true }
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
  if (chunk.usage) console.log("\n", chunk.usage);
}

智能体工具与结构化输出

通过 /v1/chat/catalog 的 models[].capabilities 查询模型能力：tool_calling、parallel_tool_calls、json_mode、structured_outputs。能力按模型区分，不支持时在生成前返回 HTTP 400。工具由你的应用执行；API 不执行函数，也不保存智能体记忆。

支持 tools（最多 128 个函数定义）、tool_choice（auto、none、required 或指定函数）、parallel_tool_calls（布尔值，需要 tools）。函数包含 name、description、JSON Schema parameters 和可选 strict。工具调用返回 message.tool_calls，content 可以为 null。将 assistant 消息原样加入历史，再为每个调用添加一条 role: "tool" 消息，填写对应 tool_call_id。下一次模型调用前必须回传全部结果，工具失败也用工具结果说明。调用 ID 应唯一，消息顺序需保留。

流式时按 index 合并 choices[0].delta.tool_calls，拼接 function.arguments 片段，并保存出现的 id、type、function.name。参数可能跨多个数据块。只在 finish_reason: "tool_calls" 且流成功结束后执行，不能执行被截断（length）或失败的输出。工具增量也会重置 60 秒空闲超时；首段输出等待上限为 90 秒。下游应校验函数名、参数与权限，并限制智能体循环次数。

response_format 支持 text、json_object、json_schema；后者使用 json_schema: {name, schema, strict, description?}。JSON 模式应在提示词中明确要求 JSON。严格 schema 应将所有属性列为 required，并设置 additionalProperties: false；可空类型可表达可选值。JSON Schema 输出不能搭配 parallel_tool_calls: true。解析前检查 refusal、length 和错误；schema 约束结构，不保证事实正确。工具定义、参数和结果参与 token 计费，每一轮模型调用独立计费。

完整工具循环

import os, json
from openai import OpenAI

client = OpenAI(api_key=os.environ["KARMAN_API_KEY"],
                base_url="https://api.coldstart.win/v1", max_retries=0)
model = os.environ["KARMAN_MODEL"]
tools = [{"type": "function", "function": {
    "name": "lookup_memory", "description": "Read a saved preference.",
    "parameters": {"type": "object", "properties": {"topic": {"type": "string"}},
                   "required": ["topic"], "additionalProperties": False},
    "strict": True
}}]
messages = [{"role": "user", "content": "What food do I like? Use my saved memory."}]

for _ in range(4):
    reply = client.chat.completions.create(
        model=model, messages=messages, tools=tools,
        tool_choice="auto", parallel_tool_calls=False, max_tokens=512)
    choice = reply.choices[0]
    message = choice.message
    if message.refusal or choice.finish_reason not in ("stop", "tool_calls"):
        raise RuntimeError("Incomplete or refused response")
    messages.append(message.model_dump(exclude_none=True))
    if not message.tool_calls:
        print(message.content)
        break
    for call in message.tool_calls:
        try:
            if call.function.name != "lookup_memory":
                raise ValueError("Unknown function")
            args = json.loads(call.function.arguments)
            if not isinstance(args, dict) or set(args) != {"topic"} or not isinstance(args["topic"], str):
                raise ValueError("Invalid arguments")
            result = {"topic": args["topic"], "preference": "apples"}
        except (ValueError, TypeError):
            result = {"error": "Invalid tool request"}
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
else:
    raise RuntimeError("Agent round limit reached")

结构化输出示例

reply = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "I like apples. Extract this preference as JSON."}],
    response_format={"type": "json_schema", "json_schema": {
        "name": "memory", "strict": True,
        "schema": {"type": "object", "properties": {"preference": {"type": "string"}},
                   "required": ["preference"], "additionalProperties": False}
    }}, max_tokens=256)
choice = reply.choices[0]
if choice.finish_reason != "stop" or choice.message.refusal:
    raise RuntimeError("Incomplete or refused response")
memory = json.loads(choice.message.content)
print(memory)