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

# SVG 生成支持哪些推理档位？

> svg.reasoning.effort 能填哪几档由 svg.model 决定：2.6 / 6.x 系编写模型支持 none、low、medium、high、xhigh、max 六档，minimal 只有 GPT-5 初代支持。本页给出模型对照、报错含义与正确写法。

## 简短回答

`svg.reasoning.effort` 控制的是**编写 SVG 文本的那款模型**要花多少推理，**能填哪几档由 `svg.model` 决定，不是网关写死的**：

* 主流编写模型（`gpt-5.6-terra`、`gpt-6-luna` 等）：`none` / `low` / `medium` / `high` / `xhigh` / `max` 六档，**填 `minimal` 会 400**。
* `minimal` 是 GPT-5 初代（`gpt-5` / `gpt-5-mini` / `gpt-5-nano`）的档位；从 `gpt-5.1` 起官方把它换成了 `none`，之后的型号都不再接受。
* 省略 `reasoning`、传 `reasoning: null`、传 `effort: null` 都正常出图，走编写模型默认档。

所以看到「`minimal` 不支持」时，不是参数写错了，而是**这款编写模型就不认这一档**，换档位或换模型都能解决。

> [!NOTE]
>
> `output_format: "svg"` 时 `svg.model` 是**必填**的，漏了会直接返回 400 `SVG generation requires 'svg.model'.`。档位问题只在这个对象内部讨论。

## 字段要嵌套在 `svg` 里

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A minimal flat vector icon of a rocket, exactly three solid colors, geometric editable shapes, no text, no raster texture, transparent background.",
  "output_format": "svg",
  "svg": {
    "model": "gpt-5.6-terra",
    "reasoning": { "effort": "high" }
  },
  "quality": "low",
  "size": "1024x1024",
  "n": 1
}
```

> [!WARNING]
>
> **别写成顶层扁平字段。** 把档位写成 `"svg_reasoning_effort": "high"` 不会报错，也不会生效——网关会直接丢弃这个未知字段，请求按「没传 effort」处理。实测用必然被拒的 `minimal` 走扁平写法返回 **200**，放进 `svg.reasoning.effort` 才返回 400；只看到 200 就以为支持，是最容易踩的坑。

## 各编写模型支持哪些档位

下表为 2026-11-10 在 `api.apiyi.com` 实测结果，档位列表以各模型报错里回显的为准（在 `/v1/responses` 上反查；SVG 路径已对 `gpt-5.6-terra`、`gpt-6-luna`、`gpt-5-nano`、`gpt-5`、`gpt-4.1-mini` 逐一验证）：

| `svg.model` | 支持的档位 | `minimal` |
| - | - | - |
| `gpt-5.6-luna` / `gpt-5.6-sol` / `gpt-5.6-terra` | `none` / `low` / `medium` / `high` / `xhigh` / `max` | ❌ 400 |
| `gpt-6-luna` / `gpt-6-sol` / `gpt-6.1-terra` | `none` / `low` / `medium` / `high` / `xhigh` / `max` | ❌ 400 |
| `gpt-6-astra` / `gpt-6.1-sol` | `low` / `medium` / `high` / `xhigh` / `max`（**没有 `none`**） | ❌ 400 |
| `gpt-5.1` / `gpt-5.2` / `gpt-5.4` / `gpt-5.4-mini` / `gpt-5.5` | `none` / `low` / `medium` / `high`（`xhigh` 从 5.2 起才有） | ❌ 400 |
| `gpt-5` / `gpt-5-mini` / `gpt-5-nano` | `minimal` / `low` / `medium` / `high` | ✅ 200 |
| `gpt-5-codex` / `gpt-5.1-codex` 系列 | `low` / `medium` / `high` | ❌ 400 |
| `gpt-4.1`（非推理模型，实测） | 不支持 `reasoning` 参数 | ❌ 400 |

> [!TIP]
>
> **拿不准某款模型支持什么，就故意传一个它大概率不认的值（比如 `max` 或 `minimal`）看报错**——上游会把该模型接受的档位全部列出来，比查文档快，也比猜准。

## 报错怎么读

### 1. 档位不被编写模型接受（`minimal` 最常见）

```json theme={null}
{
  "error": {
    "message": "Unsupported value: 'minimal' is not supported with the 'gpt-5.6-terra' model. Supported values are: 'none', 'low', 'medium', 'high', 'xhigh', and 'max'.",
    "localized_message": "Unknown error",
    "type": "shell_api_error",
    "param": "",
    "code": "unsupported_value"
  }
}
```

`param` 为空、消息里点名了模型 —— 这是**编写模型**返回的校验，不是网关拦的。请求没有进入生成阶段，**不计费**。

### 2. 值不在枚举里（拼写错误、空串）

```json theme={null}
{
  "error": {
    "message": "Provider API error: Invalid value: 'ultra'. Supported values are: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', and 'max'.",
    "localized_message": "Unknown error",
    "type": "shell_api_error",
    "param": "svg.reasoning.effort",
    "code": "invalid_value"
  }
}
```

`param` 指向 `svg.reasoning.effort`、列表是 7 个值 —— 这是**网关侧枚举**。注意它会把 `minimal` 也列出来，**不代表你的编写模型支持**，最终仍以报错 1 的模型列表为准。

### 3. 编写模型根本不支持推理

```json theme={null}
{
  "error": {
    "message": "Unsupported parameter: 'reasoning.effort' is not supported with this model.",
    "localized_message": "Unknown error",
    "type": "shell_api_error",
    "param": "",
    "code": "unsupported_parameter"
  }
}
```

用 `gpt-4.1-mini` 这类非推理模型当编写模型时出现，**任何档位都报这个错**，只能把 `reasoning` 整个去掉。

## 确实想用 `minimal` 怎么办

把编写模型换成 GPT-5 初代即可，实测能正常出 SVG：

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A minimal flat vector icon of a single blue circle, two solid colors, geometric shapes, no text, transparent background.",
  "output_format": "svg",
  "svg": {
    "model": "gpt-5-nano",
    "reasoning": { "effort": "minimal" }
  },
  "quality": "low",
  "size": "1024x1024",
  "n": 1
}
```

返回 200，`svg_usage.reasoning_tokens` 为 0（同一提示词走 `low` 是 320）。

> [!WARNING]
>
> **不建议为了省一点编写费把 `svg.model` 降回 `gpt-5` 初代。** `minimal` 省下的是编写模型的思考 token（单价本来就低），而初代模型在矢量代码的结构、路径精度和提示词遵循上明显弱于 `gpt-5.6-terra` / `gpt-6-luna`，换来的可能是更多返工。真要压低成本，优先降 `quality` 和 `size`，那是参考图那条链路的开销，占比更大。

## 档位对出图和费用的影响

* **只影响编写模型，不影响参考图。** 图像模型先出参考图（费用记在 `usage`），文本模型再按档位思考并写 SVG（费用记在 `svg_usage`），两笔都要算。
* **`reasoning_tokens` 已包含在 `output_tokens` 里**，不要重复相加；计费按编写模型的输出单价乘 `svg_usage.output_tokens`。
* **档位越高，编写费越高。** 实测 `max` 档一次产生 4,816 reasoning tokens、`svg_usage.output_tokens` 合计 4,987；`none` 档稳定为 0。
* **但 `reasoning_tokens` 不能用来反推档位是否生效。** 同一句极简提示词下 `low` / `medium` / `high` / `xhigh` 的区间重叠严重（`medium` 甚至出现过 0），只有 `none`（恒 0）和 `max`（数千）有明显区分度。简单图形用 `low` / `medium` 就够，复杂插画、多图层结构再上 `high` 以上。

## 相关文档

> [card] [GPT Image 2.6 新能力](https://docs.apiyi.com/api-capabilities/gpt-image-2/gpt-image-2-6.md)
>
> SVG、GIF、`complexity` 与标记引导编辑的完整说明和真实结果。

> [card] [GPT-Image 系列概览](https://docs.apiyi.com/api-capabilities/gpt-image-2/overview.md)
>
> 五款模型的规格、定价、端点与常见报错。

> [card] [输出 token 为什么这么高](https://docs.apiyi.com/faq/gpt-image-output-token-calculation.md)
>
> 分辨率和 `quality` 如何影响 `output_tokens` 与单张成本。

> [card] [模型价格总表](https://docs.apiyi.com/models/index.md)
>
> 编写模型与图像模型的实时单价，以这里为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.