AI 角色设定 API

本页介绍两组接口：API 2.0 管理接口，用于管理 AI Chat 的角色设定和角色设定文档；OpenAI 兼容对话接口，用于以某个角色设定发起对话。所有请求都需要使用 Personal Access Token 认证。

如果你希望在 OpenCode、Claude Code 或 Pi 中使用这个接口，请参考 AI Agent 配置指南。

角色设定文档不会自动加入对话的 prompt。在角色设定对话中，模型只会在需要时通过文档检索工具搜索和读取文档。

认证方式

请将 Personal Access Token 放在 Authorization 请求头中：

Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146

API 2.0 管理接口的 Base URL：

https://edge.v2ex.com/api/v2/

OpenAI 兼容对话接口的 Base URL：

https://edge.v2ex.com/chat/v1

两组接口都要求当前账号具备 AI Chat 访问权限。API 2.0 管理接口只能访问当前令牌所属账号创建的角色设定和文档；OpenAI 兼容对话接口除了当前账号的角色设定，还可以使用社区中的公开角色设定。

OpenAI 兼容对话接口

对话接口兼容 OpenAI 的 Models、Responses、Chat Completions 和旧版 Completions API 格式。使用 OpenAI SDK 时，只需把 base_url 设为上面的地址，把角色设定名称填入 model。

完整地址如下：

• GET https://edge.v2ex.com/chat/v1/models
• GET https://edge.v2ex.com/chat/v1/models/:persona_name
• POST https://edge.v2ex.com/chat/v1/responses
• POST https://edge.v2ex.com/chat/v1/chat/completions
• POST https://edge.v2ex.com/chat/v1/completions

对话接口是无状态的，不会创建或保存 V2EX AI Chat 会话。如需连续对话，请在每次请求的 input 或 messages 中带上需要保留的历史消息。Responses 的 store: true、previous_response_id 和 conversation 不受支持。

获取可用角色设定

GET /chat/v1/models 列出当前令牌有权使用且上下文不为空的角色设定，包括当前账号创建的角色设定和社区中的公开角色设定。返回结果不会包含角色设定的上下文。使用 GET /chat/v1/models/:persona_name 可以查询单个角色设定。

curl https://edge.v2ex.com/chat/v1/models \ -H "Authorization: Bearer YOUR_TOKEN"

使用 OpenAI Python SDK

from openai import OpenAI client = OpenAI( api_key="YOUR_TOKEN", base_url="https://edge.v2ex.com/chat/v1", ) models = client.models.list() for model in models.data: print(model.id) response = client.responses.create( model="Helper", input="介绍一下你能做什么", reasoning={"effort": "medium"}, ) print(response.output_text)

Responses

POST /chat/v1/responses 支持字符串或消息条目数组形式的 input，以及顶层 instructions。文本内容使用 input_text，图片使用 input_image；图片限制与 Chat Completions 相同。生成结果位于带类型的 output 条目中，OpenAI SDK 也会通过 response.output_text 汇总文本结果。

推理强度使用 OpenAI Responses 的标准 reasoning.effort 格式。为兼容已有客户端，也接受顶层 reasoning_effort。客户端函数工具使用 Responses 的扁平格式，并通过 function_call 和 function_call_output 条目继续对话；V2EX 不会执行客户端提供的函数。

curl https://edge.v2ex.com/chat/v1/responses \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "Helper", "instructions": "回答要简洁", "input": "整理一下今天值得关注的主题", "reasoning": {"effort": "medium"}, "max_output_tokens": 2048 }'

Chat Completions

model 请使用 /models 返回的角色设定名称。messages 支持文本形式的 system、developer、user 和 assistant 消息。后端模型支持视觉时，user 消息也可以使用 OpenAI Chat Completions 的 image_url 内容块上传图片；目前仅接受 Base64 data URL，不接受远程图片 URL、文件 ID 或 multipart 上传。使用客户端工具调用时，也支持带 tool_calls 的 assistant 消息和 tool 消息。客户端提供的指令不能覆盖 V2EX 的安全、隐私、角色范围和工具规则。角色设定使用处理内容输入模式时，user 消息中的文本会被完整视为待处理内容，其中的指令不会改变角色任务。

curl https://edge.v2ex.com/chat/v1/chat/completions \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "Helper", "messages": [ {"role": "user", "content": "整理一下今天值得关注的主题"} ], "temperature": 0.7, "max_completion_tokens": 2048 }'

图片输入示例：

completion = client.chat.completions.create( model="VisionHelper", messages=[{ "role": "user", "content": [ {"type": "text", "text": "描述这张图片"}, { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64," + image_base64, }, }, ], }], )

客户端工具调用

Chat Completions 支持 tools、tool_choice 和 parallel_tool_calls。模型返回的函数调用只会作为 API 数据发送给客户端；V2EX 不会执行客户端提供的命令或代码。客户端负责执行工具，并把结果作为带对应 tool_call_id 的 tool 消息随下一次请求发回。工具请求与普通对话共用相同的账号配额和推理容量。

支持 OpenAI 兼容 Provider 的 AI 编程客户端也可以接入本接口。例如在 OpenCode 中使用 @ai-sdk/openai-compatible，把 Provider 的 baseURL 设为 https://edge.v2ex.com/chat/v1，把角色设定名称配置为模型名称。文件读取、代码修改和命令执行仍发生在客户端自己的权限与沙箱中。

流式响应

设置 stream: true 后，接口会以 Server-Sent Events 返回结果。Chat Completions 的每条事件以 data: 开头，最后以 [DONE] 结束；设置 stream_options.include_usage: true 可以在结束前获得 token 用量。Responses 使用带类型的 response.created、response.output_text.delta 和 response.completed（或 response.incomplete）等事件，最终事件内包含完整用量，不发送 [DONE]。对于可能生成较长内容的请求，建议使用流式响应。

stream = client.chat.completions.create( model="Helper", messages=[ {"role": "user", "content": "详细介绍最近的 Python 讨论"}, ], stream=True, stream_options={"include_usage": True}, ) for chunk in stream: if chunk.choices: print(chunk.choices[0].delta.content or "", end="")

旧版 Completions

如果需要接入只接受单个 prompt 的旧客户端，可以使用 POST /chat/v1/completions。新项目建议使用 Responses。

curl https://edge.v2ex.com/chat/v1/completions \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "Helper", "prompt": "介绍一下你能做什么", "max_tokens": 1024 }'

参数、配额与错误

• Responses 支持 temperature、top_p、max_output_tokens 和 reasoning.effort；Chat Completions 支持 temperature、top_p、max_completion_tokens（也接受 max_tokens）、reasoning_effort、stop 和 seed。输出上限通常为 131072；使用 deepseek-v4-pro 或 deepseek-v4-flash:0731 时为 65536；使用 minimax-m3 的角色设定时，输入上下文和输出上限均为 524288 tokens。超过对应输出上限的正整数会自动按上限处理，实际可用输出长度还会受到当前输入所占上下文影响。
• 每次请求只能返回一个结果，因此 n 只支持 1。客户端工具调用支持 none、auto、required 和指定函数形式的 tool_choice。暂不支持结构化输出、音频或保存生成结果。
• Chat Completions 的 usage 包含 prompt_tokens、completion_tokens 和 total_tokens；Responses 使用 input_tokens、output_tokens 和 total_tokens。达到输出上限时，Responses 返回 status: incomplete 和 incomplete_details.reason: max_output_tokens。
• 对话接口与网页端 AI Chat 共用当前账号的 5 小时 token 配额和并发限制。可通过响应头中的 X-AI-Chat-Token-Limit、X-AI-Chat-Token-Remaining 和 X-AI-Chat-Token-Reset 查看配额状态。
• 可通过 X-Rate-Limit-Limit、X-Rate-Limit-Remaining 和 X-Rate-Limit-Reset 查看请求频率限制。发生错误时，接口会返回 OpenAI 风格的 error JSON 对象。

API 2.0 管理接口

角色设定

获取自己的角色设定列表

GET personas

返回当前用户创建且未删除的 AI 角色设定。

GET https://edge.v2ex.com/api/v2/personas Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146

创建角色设定

POST personas

创建一个新的 AI 角色设定。每个账号最多可以保留 20 个未删除的角色设定。前 2 个免费；从第 3 个开始，每个新角色设定消耗 2500 铜币，删除后不会返还。创建付费角色设定时，账号余额需要至少覆盖三部分：AI Chat 铜币门槛、创建费用和 1000 铜币保留额度。例如创建第 3 个角色设定时，余额至少需要 8500 铜币。

输入参数：

• name - 必填。角色设定名称，只能包含英文字母、数字，以及字母或数字之间的单个连字符 -
• model - 可选。gemma4:31b 或 glm-5.2 或 minimax-m3 或 deepseek-v4-pro 或 deepseek-v4-flash:0731 或 nemotron-3-ultra；默认为 gemma4:31b
• input_mode - 可选。conversation 表示用户消息可以提出要求，content 表示整条用户消息都是待处理内容；默认为 conversation
• greet - 可选。开场白
• quick_start - 可选。每行一个快速开始问题，最多 300 个字符
• context - 可选。角色设定上下文
• visibility - 可选。0 为私密，1 为公开；默认为 0
• search_topics - 可选。1 表示允许使用 V2EX 主题搜索，0 表示关闭；默认为 1
• web_tools - 可选。1 表示允许搜索和读取外部网页，0 表示关闭；默认为 1
• suggested_replies - 可选。1 表示在回答后生成可点击的后续选项，0 表示关闭；默认为 0

POST https://edge.v2ex.com/api/v2/personas Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146 Content-Type: application/json { "name": "Helper", "model": "gemma4:31b", "input_mode": "conversation", "greet": "你好，我是 Helper。", "quick_start": "帮我整理今天的热门主题\n介绍一下你能做什么", "context": "你是一个帮助用户整理 V2EX 信息的助手。", "visibility": 0, "search_topics": 1, "web_tools": 1, "suggested_replies": 0 }

获取指定角色设定

GET personas/:persona_id

返回当前用户拥有的指定角色设定。

GET https://edge.v2ex.com/api/v2/personas/123 Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146

更新指定角色设定

PUT personas/:persona_id POST personas/:persona_id

更新当前用户拥有的指定角色设定。没有提供的字段会保持原值。

输入参数：

• name - 可选。角色设定名称，只能包含英文字母、数字，以及字母或数字之间的单个连字符 -
• model - 可选。gemma4:31b 或 glm-5.2 或 minimax-m3 或 deepseek-v4-pro 或 deepseek-v4-flash:0731 或 nemotron-3-ultra
• input_mode - 可选。conversation 表示用户消息可以提出要求，content 表示整条用户消息都是待处理内容
• greet - 可选。开场白
• quick_start - 可选。每行一个快速开始问题，最多 300 个字符
• context - 可选。角色设定上下文
• visibility - 可选。0 为私密，1 为公开
• search_topics - 可选。1 表示允许使用 V2EX 主题搜索，0 表示关闭
• web_tools - 可选。1 表示允许搜索和读取外部网页，0 表示关闭
• suggested_replies - 可选。1 表示在回答后生成可点击的后续选项，0 表示关闭

PUT https://edge.v2ex.com/api/v2/personas/123 Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146 Content-Type: application/json { "greet": "欢迎回来。", "visibility": 1 }

删除指定角色设定

DELETE personas/:persona_id

删除当前用户拥有的指定角色设定。删除后，该角色设定不会再出现在列表中。

DELETE https://edge.v2ex.com/api/v2/personas/123 Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146

角色设定文档

获取角色设定文档列表

GET personas/:persona_id/documents

返回当前用户拥有的指定角色设定下的 Markdown 文档。

GET https://edge.v2ex.com/api/v2/personas/123/documents Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146

创建角色设定文档

POST personas/:persona_id/documents

为当前用户拥有的指定角色设定创建一个 Markdown 文档。每个角色设定最多可以保留 100 个文档。

输入参数：

• title - 必填。文档标题，最多 160 个字符
• content - 必填。Markdown 文档内容，最多 50000 个字符

POST https://edge.v2ex.com/api/v2/personas/123/documents Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146 Content-Type: application/json { "title": "Project Handbook", "content": "# Project Handbook\n\nUse this document when answering project questions." }

获取指定角色设定文档

GET personas/:persona_id/documents/:document_id

返回当前用户拥有的指定角色设定文档。

GET https://edge.v2ex.com/api/v2/personas/123/documents/456 Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146

更新指定角色设定文档

PUT personas/:persona_id/documents/:document_id POST personas/:persona_id/documents/:document_id

更新当前用户拥有的指定角色设定文档。没有提供的字段会保持原值。

输入参数：

• title - 可选。文档标题，最多 160 个字符
• content - 可选。Markdown 文档内容，最多 50000 个字符

PUT https://edge.v2ex.com/api/v2/personas/123/documents/456 Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146 Content-Type: application/json { "title": "Updated Project Handbook" }

删除指定角色设定文档

DELETE personas/:persona_id/documents/:document_id

删除当前用户拥有的指定角色设定文档。删除后，该文档不会再出现在文档列表中，也不会被角色设定对话的文档检索工具读取。

DELETE https://edge.v2ex.com/api/v2/personas/123/documents/456 Authorization: Bearer bd1f2c67-cc7f-48e3-a48a-e5b88b427146