# 模型 API (/docs/api/native/model)



## 基础地址 [#基础地址]

<ApiBaseDomain prefix="/model/v1" />

## 接入 [#接入]

<QuickstartTabs snippets="{&#x22;curl&#x22;:&#x22;curl https://api-origin.invalid/model/v1/chat/completions \\\n  -H \&#x22;Authorization: Bearer $PRAXIS_API_KEY\&#x22; \\\n  -H \&#x22;Content-Type: application/json\&#x22; \\\n  -d '{\&#x22;model\&#x22;:\&#x22;deepseek-v4-flash\&#x22;,\&#x22;messages\&#x22;:[{\&#x22;role\&#x22;:\&#x22;user\&#x22;,\&#x22;content\&#x22;:\&#x22;你好\&#x22;}]}'&#x22;,&#x22;python&#x22;:&#x22;import os\n\nfrom openai import OpenAI\n\nclient = OpenAI(\n    base_url=\&#x22;https://api-origin.invalid/model/v1\&#x22;,\n    api_key=os.environ[\&#x22;PRAXIS_API_KEY\&#x22;],\n)\n\nresp = client.chat.completions.create(\n    model=\&#x22;deepseek-v4-flash\&#x22;,\n    messages=[{\&#x22;role\&#x22;: \&#x22;user\&#x22;, \&#x22;content\&#x22;: \&#x22;你好\&#x22;}],\n)&#x22;,&#x22;typescript&#x22;:&#x22;import OpenAI from \&#x22;openai\&#x22;;\n\nconst client = new OpenAI({\n  baseURL: \&#x22;https://api-origin.invalid/model/v1\&#x22;,\n  apiKey: process.env.PRAXIS_API_KEY,\n});\n\nconst resp = await client.chat.completions.create({\n  model: \&#x22;deepseek-v4-flash\&#x22;,\n  messages: [{ role: \&#x22;user\&#x22;, content: \&#x22;你好\&#x22; }],\n});&#x22;}" />

## 两家 SDK 怎么配 [#两家-sdk-怎么配]

| SDK           | base URL                                                                               | 认证头                                   | 能用的端点                                    |
| ------------- | -------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------- |
| OpenAI SDK    | <ApiOriginInline text="&#x22;https://api-origin.invalid/model/v1&#x22;" />             | `Authorization: Bearer`               | 对话、生成响应、文本向量、生成图像、模型列表、会话（Conversations） |
| Anthropic SDK | <ApiOriginInline text="&#x22;https://api-origin.invalid/model&#x22;" />（SDK 自己补 `/v1`） | `x-api-key` 或 `Authorization: Bearer` | 发送消息、统计 token                            |

两家用同一把 Key、同一套模型名、同一个账单，换 SDK 不换别的。会话（[创建](/docs/api/native/model/createConversation)、条目、删除）是跨调用的状态容器，形状与 OpenAI 官方 conversations 一致。

## 模型回退与自带 Key [#模型回退与自带-key]

[对话](/docs/api/native/model/createChatCompletion)的请求体可以带 `providerOptions.praxis`：

| 字段               | 作用                                   |
| ---------------- | ------------------------------------ |
| `models`         | 候选模型列表：请求的模型失败时按顺序换下一个               |
| `byok`           | 自带上游 Key（按供应商名给出）；这把 Key 不可用时自动改用平台的 |
| `order` / `only` | 指定供应商的顺序或范围，只在带 `byok` 时可用           |

响应里的 `providerMetadata.praxis` 给出这次调用的 `generationId`、`cost`、`credential`（platform 或 byok）和实际服务的 `model`；拿 `generationId` 可以[查询生成记录](/docs/api/native/model/getGeneration)。其它端点目前不接受 `providerOptions.praxis`，带上会返回 400。

## 端点 [#端点]

| 方法     | 路径                                                                                                       | 说明         | 支持     |
| ------ | -------------------------------------------------------------------------------------------------------- | ---------- | ------ |
| POST   | [`/v1/chat/completions`](/docs/api/native/model/createChatCompletion)                                    | 对话         | ● 支持   |
| POST   | [`/v1/responses`](/docs/api/native/model/createResponse)                                                 | 生成响应       | ● 支持   |
| GET    | [`/v1/responses/{response_id}`](/docs/api/native/model/retrieveResponse)                                 | 读取响应       | ● 支持   |
| DELETE | [`/v1/responses/{response_id}`](/docs/api/native/model/deleteResponse)                                   | 删除响应       | ● 支持   |
| POST   | [`/v1/responses/{response_id}/cancel`](/docs/api/native/model/cancelResponse)                            | 取消响应       | ◐ 部分支持 |
| GET    | [`/v1/responses/{response_id}/input_items`](/docs/api/native/model/listResponseInputItems)               | 列出响应输入项    | ● 支持   |
| POST   | [`/v1/responses/compact`](/docs/api/native/model/compactResponse)                                        | 压缩响应       | ○ 未支持  |
| POST   | [`/v1/responses/input_tokens`](/docs/api/native/model/countResponseInputTokens)                          | 统计输入 token | ○ 未支持  |
| POST   | [`/v1/embeddings`](/docs/api/native/model/createEmbedding)                                               | 文本向量       | ● 支持   |
| POST   | [`/v1/rerank`](/docs/api/native/model/rerank)                                                            | 重排文档       | ● 支持   |
| POST   | [`/v1/audio/speech`](/docs/api/native/model/createAudioSpeech)                                           | 合成语音       | ● 支持   |
| POST   | [`/v1/audio/transcriptions`](/docs/api/native/model/createAudioTranscription)                            | 转写音频       | ● 支持   |
| POST   | [`/v1/images/generations`](/docs/api/native/model/createImage)                                           | 生成图像       | ● 支持   |
| POST   | [`/v1/images/edits`](/docs/api/native/model/editImage)                                                   | 编辑图像       | ● 支持   |
| POST   | [`/v1/ocr`](/docs/api/native/model/createOcr)                                                            | 文档识别       | ● 支持   |
| POST   | [`/v1/videos`](/docs/api/native/model/createVideo)                                                       | 创建视频       | ● 支持   |
| GET    | [`/v1/videos`](/docs/api/native/model/listVideos)                                                        | 列出视频       | ● 支持   |
| GET    | [`/v1/videos/{video_id}`](/docs/api/native/model/retrieveVideo)                                          | 读取视频       | ● 支持   |
| GET    | [`/v1/videos/{video_id}/content`](/docs/api/native/model/downloadVideoContent)                           | 下载视频内容     | ● 支持   |
| DELETE | [`/v1/videos/{video_id}`](/docs/api/native/model/deleteVideo)                                            | 删除视频       | ● 支持   |
| POST   | [`/v1/videos/{video_id}/remix`](/docs/api/native/model/remixVideo)                                       | 混剪视频       | ○ 未支持  |
| POST   | [`/v1/messages`](/docs/api/native/model/createMessage)                                                   | 发送消息       | ● 支持   |
| POST   | [`/v1/messages/count_tokens`](/docs/api/native/model/countTokens)                                        | 统计 token   | ◐ 部分支持 |
| GET    | [`/v1/models`](/docs/api/native/model/listModels)                                                        | 列出模型       | ● 支持   |
| GET    | [`/v1/models/{model}`](/docs/api/native/model/retrieveModel)                                             | 读取模型       | ● 支持   |
| GET    | [`/v1/generation`](/docs/api/native/model/getGeneration)                                                 | 查询生成记录     | ● 支持   |
| POST   | [`/v1/conversations`](/docs/api/native/model/createConversation)                                         | 创建会话       | ● 支持   |
| GET    | [`/v1/conversations/{conversation_id}`](/docs/api/native/model/retrieveConversation)                     | 读取会话       | ● 支持   |
| POST   | [`/v1/conversations/{conversation_id}`](/docs/api/native/model/updateConversation)                       | 更新会话       | ● 支持   |
| POST   | [`/v1/conversations/{conversation_id}/items`](/docs/api/native/model/createConversationItems)            | 创建会话条目     | ● 支持   |
| GET    | [`/v1/conversations/{conversation_id}/items`](/docs/api/native/model/listConversationItems)              | 列出会话条目     | ● 支持   |
| GET    | [`/v1/conversations/{conversation_id}/items/{item_id}`](/docs/api/native/model/retrieveConversationItem) | 读取会话条目     | ● 支持   |
| DELETE | [`/v1/conversations/{conversation_id}/items/{item_id}`](/docs/api/native/model/deleteConversationItem)   | 删除会话条目     | ● 支持   |
| DELETE | [`/v1/conversations/{conversation_id}`](/docs/api/native/model/deleteConversation)                       | 删除会话       | ● 支持   |

## 与官方的差异 [#与官方的差异]

* <a href="/docs/api/native/model/createChatCompletion">对话</a>：未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* <a href="/docs/api/native/model/createResponse">生成响应</a>：未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* <a href="/docs/api/native/model/retrieveResponse">读取响应</a>：按 ID 读取一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，读取会返回 404 response\_not\_found；超过保留期（默认 30 天）后读取也会返回同样的 404。
* <a href="/docs/api/native/model/deleteResponse">删除响应</a>：按 ID 立即删除一条已保存的响应。如果创建时 store 为 false，我们不会保存这次响应，删除会返回 404 response\_not\_found。
* <a href="/docs/api/native/model/cancelResponse">取消响应</a>：仅对以 background:true 创建、且路由到具备后台生成能力的模型的响应可用：取消是 幂等的，重复调用返回同一个终态响应；我方的取消只能停止我方对上游流的继续读取， 不能保证已发往上游的算力停止计算，用量按实际收到的部分结算。对一个非后台 （同步）响应调用 cancel：如果这个响应 id 不存在（未持久化、已过期或 id 有误）， 返回 404 object\_not\_found；如果响应存在但其来源 provider 没有声明支持 cancel 操作（我们目前没有接入任何为同步响应声明该能力的上游），返回 400 native\_responses\_operation\_unsupported。这两种情况都不是尚未实现的 501 gate。
* <a href="/docs/api/native/model/listResponseInputItems">列出响应输入项</a>：列出一条已保存响应的输入项。支持 limit（1–100，默认 20）、order（asc/desc， 默认 desc，与官方一致）与基于条目 id 的 after 游标分页；has\_more/first\_id/ last\_id 均与实际返回页一致，可据此翻页且不重不漏。每个条目都带服务端签发的 id（message 为 msg\_ 前缀，function\_call/function\_call\_output/reasoning 各自 对应前缀），本次上线前已保存、尚无服务端 id 的旧数据在读取时按确定性规则补 id，不做破坏性迁移，同一游标反复读取保持稳定。以 previous\_response\_id 续接 创建的响应，其输入项列出解析后的完整输入：前序响应链已有的输入与输出条目 再加本轮自己提交的输入；若该祖先响应在我方平台未保存（例如创建时 store 为 false）或已过期删除，则只列出本轮自己提交的输入。如果创建时 store 为 false，我们不会保存这次响应，列出会返回 404 response\_not\_found。
* <a href="/docs/api/native/model/compactResponse">压缩响应</a>：把响应的输入压缩成摘要，依赖 OpenAI Responses 官方的服务端存储（store）语义，我们目前还没有实现；调用会返回 501（message 为 “This platform has not implemented … yet.”，响应头 x-should-retry 为 false），不产生副作用，官方 SDK 不会重试。
* <a href="/docs/api/native/model/countResponseInputTokens">统计输入 token</a>：只统计请求输入会消耗的 token 数、不生成内容，依赖 OpenAI Responses 官方的服务端存储（store）语义，我们目前还没有实现；调用会返回 501（message 为 “This platform has not implemented … yet.”，响应头 x-should-retry 为 false），不产生副作用，官方 SDK 不会重试。
* <a href="/docs/api/native/model/createEmbedding">文本向量</a>：未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* <a href="/docs/api/native/model/rerank">重排文档</a>：标准请求字段；不能表达的参数返回 input\_not\_representable。
* <a href="/docs/api/native/model/createAudioSpeech">合成语音</a>：melotts 输出 WAV，只支持 input（含 text/prompt 别名）、lang 和默认音频选项；aura-2-en 使用原生 speaker 名称。逐字段限制见参数表。
* <a href="/docs/api/native/model/createAudioTranscription">转写音频</a>：标准请求字段；不能表达的参数返回 input\_not\_representable。
* <a href="/docs/api/native/model/createOcr">文档识别</a>：采用 Mistral OCR 请求与响应形状，仅提供 /model/v1/ocr。model 必填；document 接受 document\_url 或 image\_url（HTTPS 或 base64 data URL），也接受 `{type:"file", file_id:"<上传所得 ID>"}`，直接读取当前租户的 File。file\_id 读取上限为 24 MiB（25,165,824 字节，共享 96 MiB 内存预算按四倍预留）；超过此上限返回 413，并提示改用 HTTPS document\_url（PDF 上限 50 MiB）。PNG/JPEG 仍限 10 MiB，按文件头识别类型；不存在或其他租户的文件统一返回 404。pages 是从 0 开始的页码数组；图片如指定 pages，只能为 `[0]`。文件读取失败不计费，请求日志仅记录 file\_id，不保存文件原文。可选功能依模型而定，不支持的选项返回 400。错误为 problem+json；providerOptions.praxis 不适用于此端点。
* <a href="/docs/api/native/model/createVideo">创建视频</a>：按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video\_second（USD/秒）。
* <a href="/docs/api/native/model/listVideos">列出视频</a>：按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video\_second（USD/秒）。
* <a href="/docs/api/native/model/retrieveVideo">读取视频</a>：按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video\_second（USD/秒）。
* <a href="/docs/api/native/model/downloadVideoContent">下载视频内容</a>：按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video\_second（USD/秒）。
* <a href="/docs/api/native/model/deleteVideo">删除视频</a>：按输出秒数计费；每秒价格见 GET /model/v1/models 的 pricing.video\_second（USD/秒）。
* <a href="/docs/api/native/model/remixVideo">混剪视频</a>：未支持，调用返回 400；不要重试。
* <a href="/docs/api/native/model/createMessage">发送消息</a>：未知顶层字段原样转发给同协议上游，由上游决定是否接受；已声明字段的类型与取值范围仍会校验，不合法时返回 400 并点名字段。
* <a href="/docs/api/native/model/countTokens">统计 token</a>：按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。
* <a href="/docs/api/native/model/listModels">列出模型</a>：OCR 模型的 type 为 ocr，pricing.page 是 USD/页的十进制字符串，为 Praxis 对 Vercel 模型列表形状的扩展；其余四项 token 价格为 0。其它模型不带 pricing.page。
* <a href="/docs/api/native/model/createConversation">创建会话</a>：创建一个会话，可选携带初始 items（一次最多 20 条）与 metadata。会话按租户分区，创建者是唯一能引用它的租户。
* <a href="/docs/api/native/model/retrieveConversation">读取会话</a>：按 ID 读取一个会话。不存在或属于其他租户都返回 404 conversation\_not\_found。
* <a href="/docs/api/native/model/updateConversation">更新会话</a>：更新一个会话的 metadata——整体替换，不与已有 metadata 合并。
* <a href="/docs/api/native/model/createConversationItems">创建会话条目</a>：向一个会话追加 items（一次最多 20 条），返回刚追加的这些 items。
* <a href="/docs/api/native/model/listConversationItems">列出会话条目</a>：按创建顺序列出会话的 items，支持 limit/after/order 分页参数。
* <a href="/docs/api/native/model/retrieveConversationItem">读取会话条目</a>：按 ID 读取会话里的单条 item。
* <a href="/docs/api/native/model/deleteConversationItem">删除会话条目</a>：删除会话里的单条 item，返回该会话对象（不是被删除的 item）。
* <a href="/docs/api/native/model/deleteConversation">删除会话</a>：删除一个会话。删除后该会话与其 items 都不能再被引用（包括作为 Responses create 的 conversation 参数）。

请求与响应字段的权威定义，见每个端点页链接的 OpenAI、Anthropic 或 Mistral 官方文档。OCR 通过 HTTP 调用，不在 OpenAI 或 Anthropic SDK 的端点中。

鉴权、限流、参数校验等平台错误按 problem+json 返回；OCR 的错误也为 problem+json，其它模型调用的错误按该端点所属格式（OpenAI 或 Anthropic）返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。