> ## 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 생성에 사용할 수 있는 reasoning effort 값은 무엇입니까?

> 전송할 수 있는 svg.reasoning.effort 값은 svg.model에 따라 다릅니다. 2.6 / 6.x author 모델은 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`부터 OpenAI는 이를 `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`에서 테스트했으며, `gpt-5.6-terra`, `gpt-6-luna`, `gpt-5-nano`, `gpt-5` 및 `gpt-4.1-mini`의 SVG 경로를 처음부터 끝까지 검증했습니다).

| `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` (5.2부터 `xhigh`) | ❌ 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`와 같은 비추론 모델이 SVG를 작성할 때 나타나는 오류입니다. **모든 티어가 실패하므로** `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
}
```

`svg_usage.reasoning_tokens`를 0으로 설정하면 200을 반환합니다. (동일한 prompt를 `low`에서 사용하면 320이 보고됩니다.)

> [!WARNING]
>
> **작성 비용을 조금 아끼기 위해 `svg.model`를 기존 `gpt-5`로 다운그레이드하지 마십시오.** `minimal`는 이미 저렴한 작성 모델의 추론 token만 줄입니다. 반면 1세대 모델은 벡터 코드 구조, 경로 정밀도, prompt 준수 측면에서 `gpt-5.6-terra` / `gpt-6-luna`보다 눈에 띄게 약하므로 재작업 비용이 발생할 수 있습니다. 비용을 줄이려면 먼저 `quality`와 `size`를 낮추십시오. 비용에서 더 큰 비중을 차지하는 참조 이미지 쪽입니다.

## 티어가 출력 및 비용에 미치는 영향

* **티어는 참조 이미지가 아니라 작성 모델에만 영향을 줍니다.** 이미지 모델이 먼저 참조 이미지를 렌더링하고 `usage` 기준으로 과금된 다음, 텍스트 모델이 SVG를 추론하고 작성하며 `svg_usage` 기준으로 과금됩니다. 두 비용이 모두 계산됩니다.
* **`reasoning_tokens`는 이미 `output_tokens`에 포함되어 있습니다.** 두 번 더하지 마세요. 과금은 작성 모델의 출력 가격에 `svg_usage.output_tokens`를 곱해 계산합니다.
* **티어가 높을수록 비용이 증가합니다.** `max` 실행 한 번에서 추론 token 4,816개와 총 `svg_usage.output_tokens`개가 발생했습니다. `none`은 일관되게 0입니다.
* **하지만 `reasoning_tokens`만으로는 티어가 적용되었는지 확인할 수 없습니다.** 동일한 간단한 prompt에서 `low` / `medium` / `high` / `xhigh` 범위가 크게 겹칩니다(`medium`은 한 번 0으로 보고되기도 했습니다). `none`(항상 0)과 `max`(수천 개)만 뚜렷하게 구분됩니다. 간단한 도형에는 `low` / `medium`이면 충분합니다. 복잡한 일러스트와 다층 구조에만 `high`보다 높은 값을 사용하세요.

## 관련 문서

> [card] [GPT 이미지 2.6 기능](https://docs.apiyi.com/ko/api-capabilities/gpt-image-2/gpt-image-2-6.md)
>
> SVG, GIF, `complexity` 및 마크업 안내 편집을 실제 결과와 함께 확인합니다.

> [card] [GPT-Image 시리즈 개요](https://docs.apiyi.com/ko/api-capabilities/gpt-image-2/overview.md)
>
> 다섯 가지 모델 모두의 사양, 과금, 엔드포인트 및 일반적인 오류입니다.

> [card] [출력 tokens가 매우 많은 이유](https://docs.apiyi.com/ko/faq/gpt-image-output-token-calculation.md)
>
> 해상도와 `quality`가 `output_tokens` 및 이미지당 비용에 미치는 영향입니다.

> [card] [모델 과금](https://docs.apiyi.com/ko/models/index.md)
>
> 작성자 및 이미지 모델의 실시간 단위 가격을 확인할 수 있으며, 신뢰할 수 있는 기준입니다.


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