> ## 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.

# Which reasoning effort values work for SVG generation?

> Which svg.reasoning.effort values you can send depends on svg.model: 2.6 / 6.x author models accept none, low, medium, high, xhigh and max, while minimal only works on the original GPT-5 family. Includes the per-model table, error meanings and the correct request shape.

## Short answer

`svg.reasoning.effort` controls how much reasoning **the text model that authors the SVG** spends, and **which values are accepted depends on `svg.model`, not on the gateway**:

* Mainstream author models (`gpt-5.6-terra`, `gpt-6-luna`, and so on): `none` / `low` / `medium` / `high` / `xhigh` / `max` — **`minimal` returns 400**.
* `minimal` belongs to the original GPT-5 generation (`gpt-5` / `gpt-5-mini` / `gpt-5-nano`). Since `gpt-5.1` OpenAI replaced it with `none`, and no later model accepts it.
* Omitting `reasoning`, sending `reasoning: null`, or sending `effort: null` all generate normally and fall back to the author model's default.

So "`minimal` is not supported" does not mean you typed the field wrong — **that author model simply does not accept the tier**. Changing the tier or the model fixes it.

> [!NOTE]
>
> With `output_format: "svg"`, `svg.model` is **required**; leaving it out returns 400 `SVG generation requires 'svg.model'.` Tier questions only apply inside that object.

## Keep the field nested inside `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]
>
> **Do not use a flat top-level field.** Writing `"svg_reasoning_effort": "high"` raises no error and has no effect — the gateway drops the unknown field and treats the request as if no effort were sent. In our tests the flat form with `minimal` returned **200**, while the same value under `svg.reasoning.effort` returned 400. A 200 alone does not prove the field took effect.

## What each author model accepts

Measured on `api.apiyi.com` on 2026-11-10. The tier lists come from what each model echoes back in its own error message (probed on `/v1/responses`; the SVG path was verified end to end for `gpt-5.6-terra`, `gpt-6-luna`, `gpt-5-nano`, `gpt-5` and `gpt-4.1-mini`):

| `svg.model` | Supported tiers | `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` (**no `none`**) | ❌ 400 |
| `gpt-5.1` / `gpt-5.2` / `gpt-5.4` / `gpt-5.4-mini` / `gpt-5.5` | `none` / `low` / `medium` / `high` (`xhigh` from 5.2 on) | ❌ 400 |
| `gpt-5` / `gpt-5-mini` / `gpt-5-nano` | `minimal` / `low` / `medium` / `high` | ✅ 200 |
| `gpt-5-codex` / `gpt-5.1-codex` series | `low` / `medium` / `high` | ❌ 400 |
| `gpt-4.1` (non-reasoning, measured) | Does not accept `reasoning` at all | ❌ 400 |

> [!TIP]
>
> **Unsure what a model supports? Send a value it probably rejects (`max` or `minimal`) and read the error** — the upstream lists every tier that model accepts, which is faster and more reliable than guessing from docs.

## Reading the errors

### 1. Tier not accepted by the author model (`minimal` is the usual case)

```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` is empty and the message names the model — this is validation from the **author model**, not the gateway. The request never reaches generation and is **not billed**.

### 2. Value outside the enum (typo, empty string)

```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` points at `svg.reasoning.effort` and seven values are listed — that is the **gateway enum**. It includes `minimal`, but that **does not mean your author model supports it**; error 1 is still the authority.

### 3. Author model has no reasoning at all

```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"
  }
}
```

This is what you get when a non-reasoning model such as `gpt-4.1-mini` authors the SVG — **every tier fails**, so drop the `reasoning` object entirely.

## If you really want `minimal`

Switch the author model to the original GPT-5 family; SVG generation works in our tests:

```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
}
```

It returns 200 with `svg_usage.reasoning_tokens` at 0 (the same prompt at `low` reports 320).

> [!WARNING]
>
> **Do not downgrade `svg.model` to the original `gpt-5` just to save a little authoring cost.** `minimal` only trims the author model's thinking tokens, which are already cheap, while the first-generation model is visibly weaker at vector code structure, path precision and prompt adherence than `gpt-5.6-terra` / `gpt-6-luna` — you may pay for it in rework. To cut cost, lower `quality` and `size` first; that is the larger, reference-image side of the bill.

## How the tier affects output and cost

* **It only affects the author model, not the reference image.** The image model renders the reference image first (billed under `usage`), then the text model thinks and writes the SVG (billed under `svg_usage`); both count.
* **`reasoning_tokens` is already included in `output_tokens`** — do not add them twice. Billing uses the author model's output price times `svg_usage.output_tokens`.
* **Higher tiers cost more.** One `max` run produced 4,816 reasoning tokens and 4,987 total `svg_usage.output_tokens`; `none` is consistently 0.
* **But `reasoning_tokens` cannot prove a tier took effect.** On the same simple prompt the `low` / `medium` / `high` / `xhigh` ranges overlap heavily (`medium` even reported 0 once); only `none` (always 0) and `max` (thousands) separate cleanly. `low` / `medium` is enough for simple shapes; go above `high` only for complex illustrations and multi-layer structure.

## Related docs

> [card] [GPT Image 2.6 capabilities](https://docs.apiyi.com/en/api-capabilities/gpt-image-2/gpt-image-2-6.md)
>
> SVG, GIF, `complexity` and markup-guided editing, with real results.

> [card] [GPT-Image series overview](https://docs.apiyi.com/en/api-capabilities/gpt-image-2/overview.md)
>
> Specs, pricing, endpoints and common errors for all five models.

> [card] [Why output tokens are so high](https://docs.apiyi.com/en/faq/gpt-image-output-token-calculation.md)
>
> How resolution and `quality` drive `output_tokens` and per-image cost.

> [card] [Model pricing](https://docs.apiyi.com/en/models/index.md)
>
> Live unit prices for author and image models — authoritative.


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