> ## 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/zh-Hant/api-capabilities/gpt-image-2/gpt-image-2-6.md)
>
> SVG、GIF、`complexity` 與標記引導編輯的完整說明和真實結果。

> [card] [GPT-Image 系列概覽](https://docs.apiyi.com/zh-Hant/api-capabilities/gpt-image-2/overview.md)
>
> 五款模型的規格、定價、端點與常見報錯。

> [card] [輸出 token 為什麼這麼高](https://docs.apiyi.com/zh-Hant/faq/gpt-image-output-token-calculation.md)
>
> 解析度和 `quality` 如何影響 `output_tokens` 與單張成本。

> [card] [模型價格總表](https://docs.apiyi.com/zh-Hant/models/index.md)
>
> 編寫模型與影像模型的即時單價，以這裡為準。


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