> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 请求参数

> 查看调用模型时常用请求参数的名称、类型、取值范围、默认行为和含义。

本页汇总 Moxus AI 常见请求参数。参数是否最终生效取决于你使用的协议、模型能力和上游供应商支持情况。未知或不支持的字段可能被上游忽略，也可能返回参数错误。

<Warning>
  不同协议不能混用请求体。OpenAI 兼容接口使用 `https://moxus.ai/v1`，Anthropic 兼容接口使用 `https://moxus.ai`，Google 兼容接口使用 `https://moxus.ai/v1beta`。
</Warning>

## 通用字段

| 参数         | 类型                      | 必填                        | 默认      | 取值范围 / 示例                                     | 含义                                   |
| ---------- | ----------------------- | ------------------------- | ------- | --------------------------------------------- | ------------------------------------ |
| `model`    | string                  | 是                         | 无       | `gpt-4o`、`claude-3-5-sonnet`、`gemini-2.5-pro` | 要调用的模型名称。请从“模型广场”复制完整名称。             |
| `messages` | array                   | Chat / Claude 必填          | 无       | `[{"role":"user","content":"..."}]`           | 多轮对话消息。OpenAI 与 Anthropic 的消息结构略有差异。 |
| `input`    | string / array / object | Responses / Embeddings 常用 | 无       | 文本、数组、多模态输入                                   | Responses API、嵌入和部分模型的输入字段。          |
| `prompt`   | string / array          | 部分补全或图像接口使用               | 无       | `"画一只猫"`                                      | 单轮提示词或图像生成提示词。                       |
| `stream`   | boolean                 | 否                         | `false` | `true` / `false`                              | 是否以流式方式返回结果。                         |
| `metadata` | object                  | 否                         | 无       | `{"trace_id":"abc"}`                          | 自定义元数据，便于业务侧追踪。不要放敏感信息。              |
| `user`     | string / object         | 否                         | 无       | `"user_123"`                                  | 客户端用户标识。部分上游支持，部分上游会忽略。              |

## 采样与长度

| 参数                      | 类型               | 默认   | 取值范围 / 示例          | 含义                                                 |
| ----------------------- | ---------------- | ---- | ------------------ | -------------------------------------------------- |
| `temperature`           | number           | 模型默认 | 通常 `0` 到 `2`       | 控制随机性。越低越稳定，越高越发散。                                 |
| `top_p`                 | number           | 模型默认 | 通常 `0` 到 `1`       | 核采样阈值。一般不要同时大幅调整 `temperature` 和 `top_p`。          |
| `top_k`                 | integer / number | 模型默认 | 正整数，供应商相关          | 限制候选 token 数。Anthropic 和 Google 常见，OpenAI 模型不一定支持。 |
| `max_tokens`            | integer          | 模型默认 | 非负整数，且不能超过模型和平台限制  | 限制输出 token 数。Chat Completions 和 Anthropic 常用。      |
| `max_completion_tokens` | integer          | 模型默认 | 非负整数，且不能超过模型和平台限制  | OpenAI 部分新模型的输出上限字段。                               |
| `max_output_tokens`     | integer          | 模型默认 | 非负整数，且不能超过模型和平台限制  | Responses API 和 Google 原生接口常用输出上限字段。               |
| `stop`                  | string / array   | 无    | `"\n"` 或 `["END"]` | OpenAI 兼容停止序列。遇到指定内容时停止生成。                         |
| `stop_sequences`        | array            | 无    | `["END"]`          | Anthropic / Google 原生停止序列。                         |
| `n`                     | integer          | `1`  | 通常为正整数             | 返回候选结果数量。会增加成本，图像生成也使用该字段。                         |
| `seed`                  | number / integer | 无    | `0` 或其他整数          | 尝试固定随机种子。可复现性取决于模型和上游。                             |

## OpenAI Chat Completions 参数

| 参数                    | 类型              | 默认      | 取值范围 / 示例                                             | 含义                                  |
| --------------------- | --------------- | ------- | ----------------------------------------------------- | ----------------------------------- |
| `messages`            | array           | 无       | system / user / assistant / tool                      | 对话消息列表。                             |
| `response_format`     | object          | 无       | `{"type":"json_object"}`、`{"type":"json_schema",...}` | 要求模型返回 JSON 或符合 JSON Schema 的结构化输出。 |
| `tools`               | array           | 无       | `[{"type":"function","function":{...}}]`              | 声明可被模型调用的工具。                        |
| `tool_choice`         | string / object | `auto`  | `auto`、`none`、指定函数                                    | 控制模型是否调用工具或强制调用某个工具。                |
| `parallel_tool_calls` | boolean         | 模型默认    | `true` / `false`                                      | 是否允许模型在一轮中并行发起多个工具调用。               |
| `logprobs`            | boolean         | `false` | `true` / `false`                                      | 是否返回 token 对数概率。并非所有模型支持。           |
| `top_logprobs`        | integer         | 无       | 通常 `0` 到 `20`                                         | 返回每个位置的候选 token 对数概率数量。             |
| `frequency_penalty`   | number          | `0`     | 通常 `-2` 到 `2`                                         | 降低重复词频。正数会减少重复表达。                   |
| `presence_penalty`    | number          | `0`     | 通常 `-2` 到 `2`                                         | 鼓励引入新主题。正数会提高话题多样性。                 |
| `logit_bias`          | object          | 无       | `{ "123": -100 }`                                     | 调整指定 token 出现概率。需要 token ID。        |
| `modalities`          | array           | 模型默认    | `["text"]`、`["text","audio"]`                         | 多模态输出类型。取决于模型支持。                    |
| `audio`               | object          | 无       | `{"voice":"alloy","format":"mp3"}`                    | 音频输出配置。仅支持音频输出的模型可用。                |

## OpenAI Responses 参数

| 参数                     | 类型              | 默认     | 取值范围 / 示例                 | 含义                        |
| ---------------------- | --------------- | ------ | ------------------------- | ------------------------- |
| `input`                | string / array  | 无      | 文本或多模态输入数组                | Responses API 的主要输入字段。    |
| `instructions`         | string          | 无      | `"You are helpful"`       | 全局指令，作用类似 system prompt。  |
| `previous_response_id` | string          | 无      | `resp_...`                | 接续上一轮 Responses 对话。       |
| `max_output_tokens`    | integer         | 模型默认   | 非负整数                      | 限制输出 token 数。             |
| `reasoning`            | object          | 模型默认   | `{"effort":"medium"}`     | 推理模型的思考配置。                |
| `text`                 | object          | 模型默认   | `{"format":{...}}`        | 文本输出格式配置。                 |
| `tools`                | array / object  | 无      | web search、function、MCP 等 | Responses API 工具配置。       |
| `tool_choice`          | string / object | `auto` | `auto`、`none`、指定工具        | 控制工具调用。                   |
| `truncation`           | string          | 模型默认   | `auto`、`disabled`         | 输入过长时的截断策略。               |
| `include`              | array           | 无      | `[...]`                   | 指定额外返回字段。                 |
| `store`                | boolean         | 上游默认   | `true` / `false`          | 是否允许上游存储结果。平台可能按通道配置控制透传。 |

## Anthropic 兼容参数

| 参数               | 类型             | 必填      | 默认                                               | 取值范围 / 示例                      | 含义                         |
| ---------------- | -------------- | ------- | ------------------------------------------------ | ------------------------------ | -------------------------- |
| `model`          | string         | 是       | 无                                                | `claude-3-5-sonnet`            | Claude 或 Anthropic 兼容模型名称。 |
| `messages`       | array          | 是       | 无                                                | user / assistant 消息            | Claude Messages 对话内容。      |
| `system`         | string / array | 否       | 无                                                | `"你是助手"`                       | 系统指令。                      |
| `max_tokens`     | integer        | 常用必填    | 无                                                | 非负整数                           | 最大输出 token 数。              |
| `temperature`    | number         | 模型默认    | 通常 `0` 到 `1`                                     | 控制随机性。部分 Claude 模型可能限制非默认采样参数。 |                            |
| `top_p`          | number         | 模型默认    | 通常 `0` 到 `1`                                     | 核采样。                           |                            |
| `top_k`          | integer        | 模型默认    | 正整数                                              | 限制候选 token 数。                  |                            |
| `stop_sequences` | array          | 无       | `["END"]`                                        | 停止序列。                          |                            |
| `stream`         | boolean        | `false` | `true` / `false`                                 | 是否流式返回。                        |                            |
| `tools`          | array          | 无       | 工具声明数组                                           | 声明 Claude 可调用工具。               |                            |
| `tool_choice`    | object         | `auto`  | `{"type":"auto"}`、`{"type":"tool","name":"..."}` | 控制工具选择。                        |                            |
| `thinking`       | object         | 模型默认    | `{"type":"enabled","budget_tokens":1024}`        | Claude 思考模式配置，取决于模型支持。         |                            |
| `metadata`       | object         | 无       | `{"user_id":"..."}`                              | 业务元数据。避免放敏感信息。                 |                            |

## Google 兼容参数

Google 原生接口通常把生成参数放在 `generationConfig` 中。Moxus AI 也兼容部分 snake\_case 字段，例如 `top_p`、`max_output_tokens`。

| 参数                                                       | 类型              | 默认   | 取值范围 / 示例                           | 含义               |
| -------------------------------------------------------- | --------------- | ---- | ----------------------------------- | ---------------- |
| `contents`                                               | array / string  | 无    | 文本或多模态 parts                        | Google 原生主要输入内容。 |
| `systemInstruction`                                      | object / string | 无    | 系统指令                                | Google 原生系统指令。   |
| `tools`                                                  | array / object  | 无    | functionDeclarations、googleSearch 等 | 工具或搜索能力声明。       |
| `generationConfig.temperature`                           | number          | 模型默认 | 通常 `0` 到 `2`                        | 控制随机性。           |
| `generationConfig.topP` / `top_p`                        | number          | 模型默认 | 通常 `0` 到 `1`                        | 核采样。             |
| `generationConfig.topK` / `top_k`                        | number          | 模型默认 | 正数                                  | 候选 token 限制。     |
| `generationConfig.maxOutputTokens` / `max_output_tokens` | integer         | 模型默认 | 非负整数                                | 输出 token 上限。     |
| `generationConfig.candidateCount`                        | integer         | `1`  | 正整数                                 | 候选结果数量。          |
| `generationConfig.stopSequences`                         | array           | 无    | `["END"]`                           | 停止序列。            |
| `generationConfig.responseMimeType`                      | string          | 无    | `application/json`、`text/plain`     | 响应 MIME 类型。      |
| `generationConfig.responseSchema`                        | object          | 无    | JSON Schema                         | 结构化输出 schema。    |
| `generationConfig.presencePenalty`                       | number          | `0`  | 供应商相关                               | 话题重复惩罚。          |
| `generationConfig.frequencyPenalty`                      | number          | `0`  | 供应商相关                               | 词频重复惩罚。          |
| `generationConfig.seed`                                  | integer         | 无    | 整数                                  | 随机种子。            |
| `generationConfig.thinkingConfig`                        | object          | 模型默认 | `{"thinkingBudget":1024}`           | 思考预算或思考开关。       |
| `generationConfig.responseModalities`                    | array           | 模型默认 | `["TEXT"]`、`["TEXT","IMAGE"]`       | 输出模态。取决于模型支持。    |

## 图像生成参数

| 参数                   | 类型              | 默认      | 取值范围 / 示例                | 含义                |
| -------------------- | --------------- | ------- | ------------------------ | ----------------- |
| `model`              | string          | 无       | 图像模型名称                   | 要调用的图像生成模型。       |
| `prompt`             | string          | 无       | `"一张产品海报"`               | 图像生成提示词。          |
| `n`                  | integer         | `1`     | `1` 到 `128`              | 生成图片数量。数量越多消耗越高。  |
| `size`               | string          | 模型默认    | `1024x1024`、`1024x1792`  | 输出尺寸。具体可选值取决于模型。  |
| `quality`            | string          | `auto`  | `auto`、`standard`、`hd` 等 | 图像质量档位。具体值取决于模型。  |
| `response_format`    | string          | 模型默认    | `url`、`b64_json`         | 图片返回格式。           |
| `background`         | string / object | 模型默认    | `transparent`、`opaque`   | 背景配置。             |
| `output_format`      | string          | 模型默认    | `png`、`jpeg`、`webp`      | 输出图片格式。           |
| `output_compression` | integer         | 模型默认    | `0` 到 `100`              | 压缩质量。通常仅部分格式支持。   |
| `stream`             | boolean         | `false` | `true` / `false`         | 是否流式返回图像生成进度或部分图。 |
| `metadata` / 额外字段    | object          | 无       | 供应商自定义                   | 用于透传供应商特定参数。      |

## 嵌入与重排参数

| 参数                | 类型             | 默认      | 取值范围 / 示例        | 含义                         |
| ----------------- | -------------- | ------- | ---------------- | -------------------------- |
| `input`           | string / array | 无       | 文本或文本数组          | 要生成向量的文本。                  |
| `model`           | string         | 无       | 嵌入模型名称           | 要调用的 embedding 模型。         |
| `encoding_format` | string         | `float` | `float`、`base64` | 向量编码格式。                    |
| `dimensions`      | integer        | 模型默认    | 正整数              | 指定输出向量维度。仅部分模型支持。          |
| `query`           | string         | 无       | 查询文本             | 重排接口的查询文本。                 |
| `documents`       | array          | 无       | 文档数组             | 重排候选文档。字段名称可能因模型或供应商不同而变化。 |

## 音频参数

| 参数                | 类型     | 默认   | 取值范围 / 示例            | 含义            |
| ----------------- | ------ | ---- | -------------------- | ------------- |
| `model`           | string | 无    | 音频模型名称               | 要调用的语音模型。     |
| `input`           | string | 无    | 要朗读或处理的文本            | TTS 或音频任务输入。  |
| `voice`           | string | 模型默认 | `alloy`、`nova` 等     | 语音音色。取决于模型支持。 |
| `instructions`    | string | 无    | 风格、语气说明              | 语音生成指令。       |
| `response_format` | string | 模型默认 | `mp3`、`wav`、`json` 等 | 响应格式。         |
| `speed`           | number | `1`  | 通常 `0.25` 到 `4`      | 语速。取决于模型支持。   |
| `stream_format`   | string | 无    | `sse`                | 流式音频返回格式。     |
| `metadata`        | object | 无    | 自定义业务字段              | 业务追踪或供应商扩展字段。 |

## 隐私相关字段

| 参数                                   | 类型      | 默认   | 平台处理            | 含义                        |
| ------------------------------------ | ------- | ---- | --------------- | ------------------------- |
| `store`                              | boolean | 上游默认 | 默认允许透传，可按通道配置禁用 | 控制上游是否存储请求或输出。            |
| `safety_identifier`                  | string  | 无    | 默认过滤，除非通道明确允许   | 上游安全风控用户标识。涉及用户隐私，谨慎使用。   |
| `stream_options.include_obfuscation` | boolean | 上游默认 | 默认过滤，除非通道明确允许   | 控制流式响应混淆行为。               |
| `metadata`                           | object  | 无    | 可能被记录或透传        | 自定义业务元数据，不要放密钥、密码或个人敏感信息。 |

## 参数使用建议

* 第一次调用只传 `model`、`messages` 或 `input`，确认模型可用后再增加参数。
* 不确定时只调一个采样参数，优先调整 `temperature`。
* 成本敏感场景设置 `max_tokens` 或 `max_output_tokens`。
* 使用工具调用时，先用简单 schema 测通，再增加复杂字段。
* 不要把 API 密钥、数据库连接串、身份证号等敏感信息放入 `metadata` 或提示词。

## 相关文档

* [快速入门](/zh/overview/quickstart)
* [结构化输出](/zh/guide/structured-output)
* [函数调用](/zh/guide/function-calling)
* [隐私与数据](/zh/platform/privacy)