对话补全

OpenAI 兼容的对话补全端点。如果你已经在使用 OpenAI SDK，只需更改 base_url 和 api_key 即可无缝迁移。

POST https://api.profy.cn/v1/chat/completions

认证

支持两种认证方式：

API Key：Authorization: Bearer sk-pro-xxxx
OAuth Bearer：Authorization: Bearer <access_token>

请求体

model

string

必填

模型标识符。使用 GET /v1/models 查询可用模型。

messages

array

必填

对话消息数组。每条消息包含 role 和 content 字段。

stream

boolean

默认值:"false"

是否使用 SSE 流式返回。

temperature

number

采样温度，范围 0-2。值越高输出越随机。部分模型不支持此参数（参见模型 capabilities）。

max_tokens

integer

生成的最大 token 数。

top_p

number

Nucleus sampling 参数。

frequency_penalty

number

频率惩罚参数，范围 -2.0 到 2.0。

presence_penalty

number

存在惩罚参数，范围 -2.0 到 2.0。

stop

string | string[]

停止生成的标记。

tools

array

Function Calling 工具定义数组（与 OpenAI 格式一致）。

tool_choice

string | object

工具选择策略："auto"、"none" 或指定工具。

非流式请求示例

from profy import Profy

async with Profy(api_key="sk-pro-your-key") as client:
    resp = await client.chat.completions.create(
        model="deepseek-v3",
        messages=[
            {"role": "system", "content": "你是一个专业的翻译助手"},
            {"role": "user", "content": "把这句话翻译成英文：今天天气真好"},
        ],
        temperature=0.3,
    )
    print(resp.text)

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

const resp = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [
    { role: "system", content: "你是一个专业的翻译助手" },
    { role: "user", content: "把这句话翻译成英文：今天天气真好" },
  ],
  temperature: 0.3,
});

console.log(resp.text);

curl -X POST https://api.profy.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3",
    "messages": [
      {"role": "system", "content": "你是一个专业的翻译助手"},
      {"role": "user", "content": "把这句话翻译成英文：今天天气真好"}
    ],
    "temperature": 0.3
  }'

非流式响应

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "deepseek-v3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The weather is really nice today."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 8,
    "total_tokens": 36
  },
  "balance_remaining": 9500
}

响应中额外包含 balance_remaining 字段，返回调用后的剩余积分余额。这是与 OpenAI 的主要差异之一。

流式请求示例

from profy import Profy

async with Profy(api_key="sk-pro-your-key") as client:
    stream = await client.chat.completions.create(
        model="deepseek-v3",
        messages=[{"role": "user", "content": "讲一个笑话"}],
        stream=True,
    )
    async for chunk in stream:
        if chunk.delta:
            print(chunk.delta, end="", flush=True)

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

const stream = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [{ role: "user", content: "讲一个笑话" }],
  stream: true,
});

for await (const chunk of stream) {
  if (chunk.delta) {
    process.stdout.write(chunk.delta);
  }
}

curl -N -X POST https://api.profy.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3",
    "messages": [{"role": "user", "content": "讲一个笑话"}],
    "stream": true
  }'

作为 OpenAI 替代

如果你正在使用 OpenAI 的官方 SDK，只需修改 base_url 和 api_key：

from openai import OpenAI

client = OpenAI(
    api_key="sk-pro-your-key",
    base_url="https://api.profy.cn/v1",
)

response = client.chat.completions.create(
    model="deepseek-v3",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-pro-your-key",
  baseURL: "https://api.profy.cn/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [{ role: "user", content: "你好" }],
});
console.log(response.choices[0].message.content);

调用袋袋专家（Expert-as-Model）

除了直接调用裸模型，你还可以通过 profy-<identifier> 格式的模型名调用袋袋平台上已发布的专家（AI Agent）。专家背后是完整的 Agent 能力栈：人格、工具调用、记忆、技能——而你只需像调用普通模型一样使用它。

模型命名约定

格式	含义	示例
`profy-<identifier>`	调用指定的袋袋专家	`profy-financial-advisor`
其他模型名	直接调用裸 LLM（现有行为）	`deepseek-v3`

使用 GET /v1/models 可以查询所有可用的专家模型（type: "expert"）。

请求示例（非流式）

默认行为（stream 省略或为 false）：Agent 完成全部推理和工具调用后，一次性返回完整 JSON 响应。

from openai import OpenAI

client = OpenAI(
    api_key="sk-pro-your-key",
    base_url="https://api.profy.cn/v1",
)

response = client.chat.completions.create(
    model="profy-financial-advisor",
    messages=[
        {"role": "user", "content": "帮我分析一下特斯拉最近的财报"}
    ],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-pro-your-key",
  baseURL: "https://api.profy.cn/v1",
});

const response = await client.chat.completions.create({
  model: "profy-financial-advisor",
  messages: [
    { role: "user", content: "帮我分析一下特斯拉最近的财报" },
  ],
});

console.log(response.choices[0].message.content);

curl -X POST https://api.profy.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "profy-financial-advisor",
    "messages": [
      {"role": "user", "content": "帮我分析一下特斯拉最近的财报"}
    ]
  }'

请求示例（流式）

设置 stream: true 可实时接收增量内容，适合需要即时展示文字的场景。

from openai import OpenAI

client = OpenAI(
    api_key="sk-pro-your-key",
    base_url="https://api.profy.cn/v1",
)

response = client.chat.completions.create(
    model="profy-financial-advisor",
    messages=[
        {"role": "user", "content": "帮我分析一下特斯拉最近的财报"}
    ],
    stream=True,
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-pro-your-key",
  baseURL: "https://api.profy.cn/v1",
});

const stream = await client.chat.completions.create({
  model: "profy-financial-advisor",
  messages: [
    { role: "user", content: "帮我分析一下特斯拉最近的财报" },
  ],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

curl -N -X POST https://api.profy.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "profy-financial-advisor",
    "messages": [
      {"role": "user", "content": "帮我分析一下特斯拉最近的财报"}
    ],
    "stream": true
  }'

多轮对话（Session）

首次调用时系统自动创建 session，session ID 通过响应头 X-Session-Id 返回。后续调用通过以下任一方式传入 session ID 来续接对话：

请求体 session_id 字段（推荐，OpenAI SDK 通过 extra_body 传递）
请求头 X-Session-Id

from openai import OpenAI

client = OpenAI(
    api_key="sk-pro-your-key",
    base_url="https://api.profy.cn/v1",
)

# 第一轮
r1 = client.chat.completions.create(
    model="profy-financial-advisor",
    messages=[{"role": "user", "content": "我叫小明，帮我做个投资计划"}],
    extra_body={}
)
session_id = r1._headers.get("x-session-id")

# 第二轮 — 专家记得你的名字和上下文
r2 = client.chat.completions.create(
    model="profy-financial-advisor",
    messages=[{"role": "user", "content": "你还记得我叫什么吗？"}],
    extra_body={"session_id": session_id}
)

Expert-as-Model 与 Agents Run 的对比

特性	`/v1/chat/completions` + `profy-*`	`/v1/agents/run`
SDK 兼容性	OpenAI SDK 直接使用	需要 Profy SDK
响应格式	OpenAI Chat Completions 标准格式	Profy 自定义 SSE 事件
流式 / 非流式	均支持（`stream` 默认 `false`）	仅流式
工具调用过程	静默（Agent 内部消化）	16 种事件全量暴露
适用场景	drop-in 替换、LangChain 集成、快速接入	需要工具可观测性、构建自定义 UI

如果你需要观测 Agent 的完整工具调用过程（如展示”正在搜索…”、“正在分析数据…”等中间状态），请使用 /v1/agents/run 端点配合 Profy SDK。

与 OpenAI 的差异

特性	袋袋	OpenAI
模型名称	袋袋平台模型标识符	OpenAI 模型名
额外返回字段	`balance_remaining`（剩余积分）	无
Function Calling	支持（部分模型）	全量支持
Vision	支持（部分模型）	支持
计费方式	袋袋积分	美元

使用 GET /v1/models 查询每个模型的 capabilities，了解该模型是否支持 temperature、tools、vision 等功能。

错误码

HTTP 状态码	说明
`400`	缺少 `model` 或 `messages`，或模型不可用
`401`	认证失败
`502`	上游模型提供商返回错误

概览

Platform API

认证与密钥

集成

SDK

Cookbook

参考

认证

请求体

非流式请求示例

非流式响应

流式请求示例

作为 OpenAI 替代

调用袋袋专家（Expert-as-Model）

模型命名约定

请求示例（非流式）

请求示例（流式）

多轮对话（Session）

Expert-as-Model 与 Agents Run 的对比

与 OpenAI 的差异

错误码

下一步

模型列表

上报计费事件

​认证

​请求体

​非流式请求示例

​非流式响应

​流式请求示例

​作为 OpenAI 替代

​调用袋袋专家（Expert-as-Model）

​模型命名约定

​请求示例（非流式）

​请求示例（流式）

​多轮对话（Session）

​Expert-as-Model 与 Agents Run 的对比

​与 OpenAI 的差异

​错误码

​下一步

模型列表

上报计费事件

认证

请求体

非流式请求示例

非流式响应

流式请求示例

作为 OpenAI 替代

调用袋袋专家（Expert-as-Model）

模型命名约定

请求示例（非流式）

请求示例（流式）

多轮对话（Session）

Expert-as-Model 与 Agents Run 的对比

与 OpenAI 的差异

错误码

下一步