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

# Grok Imagine 2 이미지 생성 및 편집

> APIYI에서 xAI의 최신 세대 이미지 모델(grok-imagine-image / grok-imagine-image-quality)에 대한 완전한 안내서입니다 — 5개의 화면 비율, 1K/2K 등급, 호출당 최대 10개 이미지, 진정한 참조 이미지 편집, 이미지당 고정 $0.02 / $0.045.

## 개요

**Grok Imagine 2**는 xAI의 **최신 2세대** 이미지 모델로, 첫 번째 릴리스에서 파라미터 제어와 편집 양쪽 모두에서 완전한 세대 도약을 이뤘습니다. 종횡비와 해상도가 실제로 반영되고, 2K 단계가 제공되며, 한 번의 호출로 최대 10장의 이미지를 반환하고, 참조 편집은 원본 이미지를 정말로 보존합니다.

APIYI는 두 가지 버전인 `grok-imagine-image`(표준)과 `grok-imagine-image-quality`(고품질)을 제공합니다. 둘은 동일한 엔드포인트와 파라미터를 공유하며 — 차이는 출력 충실도와 가격뿐입니다.

<Note>
  **주요 특징**: 요청당 정액 요금(**1K와 2K 요금이 동일합니다**), 5가지 종횡비 x 2단계 해상도가 **실제로 반영되며**, 한 번의 호출당 최대 10장 이미지, 그리고 아트 스타일, 구도, 팔레트, 피사체 동일성을 보존하는 고충실도 참조 편집입니다. 1K 이미지는 약 9초가 걸립니다.
</Note>

<Info>
  **모델 ID에는 `2`가 포함되지 않습니다.** 제품명은 Grok Imagine 2이지만, 호출하는 모델 이름은 \*\*`grok-imagine-image`\*\*와 \*\*`grok-imagine-image-quality`\*\*입니다. `grok-imagine-2-image`라고 쓰지 마십시오. 해당 모델이 없으므로 503이 반환됩니다.
</Info>

<Warning>
  **📌 먼저 읽으십시오**: **참조 이미지는 편집 엔드포인트 `/v1/images/edits`에서만 작동하며 — 텍스트-이미지에서는 절대 사용할 수 없습니다.**

  `image` / `image_url` / `images`를 `/v1/images/generations`에 전달하면 **정상적인 이미지와 함께 200이 반환되지만**, 참조는 **조용히 버려지며** 여전히 과금됩니다 — 어떠한 오류도 발생하지 않습니다. 아래 [엔드포인트](#endpoints)를 참고하십시오.
</Warning>

<Info>
  모든 이미지 API는 **동기식**입니다. 비동기 작업 ID가 없으므로, 클라이언트가 연결을 끊으면 요청은 여전히 과금되는 동안 결과는 사라집니다. 넉넉한 타임아웃을 설정하십시오 — [이미지 API 모범 사례](/ko/api-capabilities/image-api-best-practices)를 참고하십시오.
</Info>

<CardGroup cols={2}>
  <Card title="텍스트-이미지 API" icon="wand-sparkles" href="/ko/api-capabilities/grok-imagine-image/text-to-image">
    텍스트 prompt에서 이미지를 생성하며, 실시간 테스트를 위한 인터랙티브 플레이그라운드를 제공합니다.
  </Card>

  <Card title="이미지 편집 API" icon="image" href="/ko/api-capabilities/grok-imagine-image/image-edit">
    참조 이미지와 지시문을 업로드하며, 1-3장 이미지 융합과 플레이그라운드를 제공합니다.
  </Card>
</CardGroup>

## APIYI에서 Grok Imagine 2를 선택해야 하는 이유

<CardGroup cols={2}>
  <Card title="OpenAI 호환 형식" icon="shield-check">
    표준 `/v1/images/generations` 및 `/v1/images/edits` 엔드포인트. 요청 본문과 응답 필드는 OpenAI 이미지 API와 일치하므로, 공식 OpenAI SDK를 바로 사용할 수 있습니다 — 마이그레이션 작업이 전혀 필요하지 않습니다.
  </Card>

  <Card title="동시 실행 수 제한 없음" icon="infinity">
    RPM/RPD 하드 제한이 없습니다. **100 RPM에서도 충분히 안정적으로 측정됨**으로 넉넉한 채널 용량을 확보하고 있어, 배치 워크로드가 선형적으로 확장됩니다 — 쿼터 요청이나 자체 스로틀링이 필요하지 않습니다.
  </Card>

  <Card title="정액 요금, 예측 가능한 비용" icon="percent">
    이미지당 고정 요금이며, **해상도와 무관합니다** — 2K 이미지의 비용은 1K와 같습니다. 정확한 이미지 수 기준으로 예산을 책정하고, [충전 보너스](/ko/faq/recharge-promotions)를 중첩해 더 낮출 수 있습니다.
  </Card>

  <Card title="전 세계에서 접근 가능, 장벽 없음" icon="globe">
    **해외 서버나 프록시가 필요하지 않습니다.** 중국 본토 데이터 센터, 가정용 광대역, 해외 노드 모두 `api.apiyi.com`에 직접 연결됩니다.
  </Card>

  <Card title="전체 모델 생태계" icon="layers">
    또한 이용 가능합니다: [Nano Banana 2](/ko/api-capabilities/nano-banana-2-image/overview), [GPT-Image-2](/ko/api-capabilities/gpt-image-2/overview), [Seedream](/ko/api-capabilities/seedream-image/overview), [FLUX](/ko/api-capabilities/flux/overview), 그리고 [Grok 텍스트 모델](/ko/api-capabilities/grok/overview).
  </Card>

  <Card title="전문 지원" icon="handshake">
    저희 팀은 이미지 생성 워크로드를 깊이 다뤄 왔으며, PoC부터 프로덕션 롤아웃까지 엔터프라이즈 고객을 지원할 수 있습니다.
  </Card>
</CardGroup>

## 주요 기능

<CardGroup cols={2}>
  <Card title="두 가지 해상도 등급" icon="expand">
    `1k` 약 1메가픽셀, `2k` 4.2\~4.5메가픽셀(16:9 기준 2816x1584) — **동일한 가격**
  </Card>

  <Card title="5가지 화면 비율" icon="maximize">
    `1:1` / `16:9` / `9:16` / `4:3` / `3:4`, 실측된 픽셀 크기가 정확히 일치합니다
  </Card>

  <Card title="호출당 최대 10개" icon="images">
    `n`는 1\~10개를 허용하며, 한 번의 요청으로 여러 이미지를 반환합니다 — 배치 선택에 이상적입니다
  </Card>

  <Card title="빠른 생성" icon="zap">
    1K에서는 약 9초, 2K에서는 15\~17초이며, 부하가 걸려도 지연 시간이 안정적입니다 — 100 RPM도 무난히 처리됩니다
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="진정한 참조 편집" icon="wand">
    요청한 부분만 변경됩니다 — 아트 스타일, 구도, 팔레트 및 피사체 정체성은 그대로 유지됩니다
  </Card>

  <Card title="다중 이미지 융합" icon="layers-2">
    편집 엔드포인트는 참조 이미지 1\~3개를 허용합니다. 예를 들어 이미지 A의 피사체를 이미지 B의 장면과 스타일에 넣는 방식입니다
  </Card>

  <Card title="두 가지 응답 형식" icon="file-json">
    `url` 직접 링크 또는 `b64_json` 원시 base64를 두 엔드포인트 모두에서 지원합니다
  </Card>

  <Card title="OpenAI SDK 바로 사용 가능" icon="plug">
    `client.images.generate()`와 `client.images.edit()`는 바로 작동합니다 — 수동 HTTP 구성은 필요 없습니다
  </Card>
</CardGroup>

## 요금

| 모델                               | 과금 방식     | APIYI 가격          | 비고            |
| -------------------------------- | --------- | ----------------- | ------------- |
| **`grok-imagine-image`**         | 요청당 정액 요금 | **\$0.02 / 이미지**  | 표준 등급, 기본 옵션  |
| **`grok-imagine-image-quality`** | 요청당 정액 요금 | **\$0.045 / 이미지** | 고품질 출력용 고급 등급 |

<Info>
  **과금 참고사항**

  * **해상도와 무관**: `1k` 및 `2k`는 비용이 동일합니다 — 2K에는 추가 요금이 없습니다.
  * **이미지당**: `n=4`는 prompt 길이에 관계없이 4개 이미지로 과금됩니다.
  * **편집 요금은 텍스트-이미지와 동일합니다** — `/v1/images/edits`에는 추가 요금이 없습니다.
  * **`usage` 블록은 정산에 사용할 수 없습니다**: `prompt_tokens`는 항상 `1000 x n`이며, 플레이스홀더입니다. 대신 콘솔 과금 기록을 사용하십시오.
</Info>

## 그룹 설정

Grok Imagine 2는 위의 가격표와 일치하는 \*\*`Default` 그룹(1.0x 요율)\*\*에서 실행됩니다. **그룹 전환은 필요하지 않습니다.**

**권장 Token 과금 모델**: `Pay-as-you-go Priority`. 이 패밀리는 요청당 과금되며, Pay-as-you-go Priority와 Pay-per-request는 모두 올바르게 라우팅됩니다 — Pay-as-you-go Priority를 선택하면 하나의 Token으로 플랫폼의 다른 token 과금 모델도 함께 사용할 수 있습니다.

<Tip>
  Token이 이미 다른 이미지 모델을 포함하고 있다면 `Default`을 기본 그룹으로 유지하면 됩니다. 이 패밀리는 전용 그룹이나 추가 설정이 필요하지 않습니다.
</Tip>

## 기술 사양

| 항목                  | 사양                                                 |
| ------------------- | -------------------------------------------------- |
| 모델 ID               | `grok-imagine-image`, `grok-imagine-image-quality` |
| 화면 비율               | 5: `1:1` / `16:9` / `9:16` / `4:3` / `3:4`         |
| 해상도 등급              | `1k` (\~0.9-1.05 MP), `2k` (\~4.2-4.5 MP)          |
| 출력 형식               | **1K의 JPEG(\~220-300 KB), 2K의 PNG(\~5-6 MB)**      |
| 호출당 이미지 수           | `n` 1-10                                           |
| 참조 이미지              | 편집 엔드포인트에서 1-3개(반복 `image[]`)                      |
| 마스크 인페인팅            | ❌ 지원되지 않습니다                                        |
| 재현 가능한 `seed`       | ❌ 지원되지 않습니다                                        |
| `revised_prompt` 에코 | ❌ 반환되지 않습니다                                        |
| 지연 시간               | 1K에서 \~9초, 2K에서 \~15-17초                           |
| 동시 실행 수 / 요청 속도     | 제한 없음; **100 RPM에서도 무난하게 측정됩니다**                   |
| 권장 클라이언트 타임아웃       | 360초 이상                                            |

## 엔드포인트

| 기능        | Method | Path                     | Content-Type              |
| --------- | ------ | ------------------------ | ------------------------- |
| 텍스트-투-이미지 | `POST` | `/v1/images/generations` | `application/json`        |
| 이미지 편집    | `POST` | `/v1/images/edits`       | **`multipart/form-data`** |
| 채팅 스타일 생성 | `POST` | `/v1/chat/completions`   | `application/json`        |

<Warning>
  **✅ 편집 엔드포인트는 `multipart/form-data` 파일 업로드가 필요합니다**

  `/v1/images/edits`에 JSON을 보내면 **항상 400이 반환됩니다**:

  ```text theme={null}
  request Content-Type isn't multipart/form-data
  ```

  **상위 벤더의 문서에서 통합하는 경우 특히 중요합니다** — 해당 문서는 공개 이미지 URL이 포함된 JSON 본문을 설명하지만, 이는 APIYI 게이트웨이를 통해서는 **작동하지 않습니다**. **대신 이 페이지를 따르십시오**: `-F "image=@photo.jpg"`로 파일을 업로드하십시오. 전체 예시는 [이미지 편집 API](/ko/api-capabilities/grok-imagine-image/image-edit)에서 확인하십시오.

  파일 필드는 `image` 또는 `image[]`로 이름이 지정되어야 하며, `images` / `image_file`는 415를 반환합니다.
</Warning>

<Warning>
  **⚠️ 텍스트-투-이미지 엔드포인트에는 참조 이미지를 절대 보내지 마십시오**

  `/v1/images/generations`가 `image` / `image_url` / `images`를 받으면 오류를 발생시키지 않습니다. 200을 반환하고 참조를 완전히 무시한 채 prompt만으로 새 이미지를 생성하며 — **평소와 같이 과금됩니다**.

  오류 신호가 없기 때문에, 이 문제는 보통 출력이 입력과 전혀 관련이 없다는 것을 누군가 알아차릴 때에야 드러납니다. **참조 이미지를 포함하는 모든 워크플로는 `/v1/images/edits`를 사용해야 합니다.**
</Warning>

<Tip>
  주 도메인 `https://api.apiyi.com`, 백업 `https://vip.apiyi.com`입니다. 채팅 스타일 생성(`/v1/chat/completions`)은 작동하지만 **권장 경로는 아닙니다** — 아래 FAQ를 참조하십시오.
</Tip>

## GPT-Image-2에서 이전하기

이미 [GPT-Image-2](/ko/api-capabilities/gpt-image-2/overview)를 통합해 두셨다면, **엔드포인트와 호출 규약은 동일합니다**(`/v1/images/generations` + `/v1/images/edits`, OpenAI SDK와 호환) — 그러나 **파라미터 체계는 다르므로**, 모델 이름만 바꿔서는 동작하지 않습니다. 변경해야 할 내용은 다음과 같습니다.

### 파라미터 매핑

| 항목         | GPT-Image-2                                           | **Grok Imagine 2**                | 이전 조치                                       |
| ---------- | ----------------------------------------------------- | --------------------------------- | ------------------------------------------- |
| 출력 크기      | `size`(`1536x1024` 같은 명시적 픽셀)                         | `aspect_ratio` + `resolution`     | **반드시 다시 작성해야 합니다**; `size`는 오류를 발생시키지 않습니다 |
| 품질 등급      | `quality`(`low`/`medium`/`high`/`auto`)               | 해당 파라미터는 없습니다 — **모델 이름을 사용합니다**  | `quality`를 제거하고, `-quality` 변형으로 전환합니다      |
| 출력 형식      | `output_format`(png/jpeg/webp) + `output_compression` | 해당 파라미터는 없습니다 — **형식은 해상도를 따릅니다** | 둘 다 제거합니다. 1K는 항상 JPEG이고, 2K는 항상 PNG입니다     |
| 배경         | `background`(`opaque`/`auto`)                         | 해당 파라미터는 없습니다                     | 제거합니다                                       |
| 모더레이션 수준   | `moderation`(`auto`/`low`)                            | 해당 파라미터는 없습니다                     | 제거합니다                                       |
| 고충실도       | `input_fidelity`는 전송하면 안 됩니다                          | 해당 파라미터는 없습니다                     | 제거합니다                                       |
| 호출당 이미지 수  | `n`는 **1개만 지원합니다**                                    | `n`는 **1-10개를 지원합니다**             | ✅ 클라이언트 측 팬아웃 루프를 제거할 수 있습니다                |
| 참조 이미지(편집) | 최대 16개                                                | **최대 3개**                         | ⚠️ 3개를 초과해 보내는 흐름은 다시 구성해야 합니다              |
| 마스크 인페인팅   | ✅ 지원됨                                                 | ❌ **지원되지 않음**                     | ⚠️ 마스크에 의존하는 흐름은 이전할 수 없습니다                 |
| 과금         | token당(\~\$0.21/이미지, high 기준)                         | **요청당 정액**, \$0.02 / \$0.045      | 예산 모델이 사용량 기반에서 이미지당 과금으로 바뀝니다              |

### 가장 쉽게 하는 세 가지 실수

<Warning>
  **1. 기본 응답 형식이 반대로 되어 있어 가장 자주 놓치는 변경 사항입니다**

  GPT-Image-2는 **`b64_json`만 반환합니다**(`url`는 없습니다), 반면 Grok Imagine 2는 **기본적으로 `url`를 반환합니다**. 파서가 `resp.data[0].b64_json`를 읽는다면, 이전 후에는 `None` / `undefined`를 받게 됩니다.

  다음 두 가지 해결책 중 하나를 선택하십시오:

  * **기존 코드를 유지하려면** → `"response_format": "b64_json"`를 명시적으로 전달합니다
  * **직접 링크로 전환하려면** → `data[0].url`를 읽어 다운로드합니다

  또한 GPT-Image-2의 `usage`는 **실제 token 수**를 담고 있는 반면, Grok Imagine 2의 `usage`는 **플레이스홀더**(항상 `1000 x n`)입니다. `usage`을 기반으로 만든 비용 보고 스크립트는 이전 후 잘못된 수치를 산출합니다.
</Warning>

<Warning>
  **2. `size`는 오류를 내지 않고 조용히 실패합니다**

  GPT-Image-2는 검증이 엄격하며 보통 잘못된 입력에 대해 400을 반환합니다. **Grok Imagine 2는 관대합니다**: `size`, `quality`, `style` 같은 OpenAI 스타일 필드는 **조용히 무시되며**, 잘못된 `aspect_ratio` / `resolution` 값은 **조용히 기본값으로 되돌아갑니다**.

  따라서 `model`만 바꾸고 `size: "1536x1024"`를 제거하는 것을 잊으면, 요청은 **1024x1024 정사각형 이미지를 반환하면서 200으로 성공합니다** — 해당 파라미터가 무시되었다는 사실을 알려주는 내용은 없습니다.

  이전 후에는 **첫 호출에서 출력 픽셀 크기를 확인하여** `aspect_ratio` / `resolution`가 실제로 적용되었는지 검증하십시오.
</Warning>

<Warning>
  **3. 참조 이미지는 더 이상 텍스트-투-이미지 엔드포인트로 보낼 수 없습니다**

  이 함정은 이 모델에만 해당합니다. `/v1/images/generations`로 참조 이미지를 보내면 **200을 반환하고, 참조를 조용히 폐기하면서도 과금은 계속됩니다**. 모든 참조 이미지 호출은 `/v1/images/edits`를 `multipart/form-data`와 함께 사용해야 합니다 — 위의 [Endpoints](#endpoints)를 보십시오.
</Warning>

### 변경 전과 후

```python theme={null}
# Before: GPT-Image-2
resp = client.images.generate(
    model="gpt-image-2",
    prompt="Cyberpunk city on a rainy night",
    size="1536x1024",           # <- remove
    quality="high",             # <- remove
    output_format="jpeg"        # <- remove
)
img = base64.b64decode(resp.data[0].b64_json)

# After: Grok Imagine 2
resp = client.images.generate(
    model="grok-imagine-image",           # use grok-imagine-image-quality for higher fidelity
    prompt="Cyberpunk city on a rainy night",
    n=1,
    extra_body={
        "aspect_ratio": "16:9",           # <- replaces size
        "resolution": "1k",               # <- replaces the sizing role of quality
        "response_format": "b64_json"     # <- set explicitly to keep the parser unchanged
    }
)
img = base64.b64decode(resp.data[0].b64_json)
```

<Tip>
  **어느 것을 사용해야 합니까?** 마스크 인페인팅, 픽셀 단위로 정확한 사용자 지정 크기, 또는 최대 16개 참조를 통한 융합이 필요하면 [GPT-Image-2](/ko/api-capabilities/gpt-image-2/overview)에 그대로 머무르십시오. **예측 가능한 비용**(이미지당 정액, 2K 추가 요금 없음), **호출당 여러 이미지**(`n` 최대 10개), 또는 **편집 시 높은 원본 충실도**가 필요하면 Grok Imagine 2를 선택하십시오. 두 모델은 공존하며 — 동일한 Token으로 둘 다 호출합니다.
</Tip>

## 주요 매개변수

### `aspect_ratio` 및 `resolution` (출력 크기)

이 둘은 함께 실제 출력 픽셀을 결정합니다. 측정된 값은 요청값과 정확히 일치합니다:

| `aspect_ratio` | `resolution: 1k` | `resolution: 2k` |
| -------------- | ---------------- | ---------------- |
| `1:1`          | 1024x1024        | 2048x2048        |
| `16:9`         | 1280x720         | 2816x1584        |
| `9:16`         | 720x1280         | 1584x2816        |
| `4:3`          | 1152x864         | 2368x1776        |
| `3:4`          | 864x1152         | 1776x2368        |

<Warning>
  **두 매개변수는 텍스트-투-이미지에만 적용됩니다.** `/v1/images/edits`에서는 오류 없이 허용되지만 **효과가 없습니다** — 편집된 출력은 항상 **입력 참조 이미지의 크기**와 일치합니다(입력 1280x720, 출력 1280x720). 출력 크기를 변경하려면 업로드하기 전에 참조 이미지를 자르거나 크기를 조정하십시오.
</Warning>

<Info>
  **검증은 느슨합니다 — 오타가 있어도 오류가 발생하지 않습니다.** `aspect_ratio`의 enum 범위를 벗어난 값(예: `5:7`, `21:9`)이나 `resolution`의 값(예: `1K`, `1024x1024`)은 **조용히 기본값으로 되돌아가며** 여전히 이미지를 반환합니다. 잘못된 `response_format` 역시 `url`로 되돌아갑니다. 따라서 출력이 예상과 다를 때는 **먼저 매개변수 철자를 확인하십시오**.

  유일한 예외는 `resolution: "4k"`이며, 이는 `503 model_service_unavailable`를 반환합니다. 이는 **티어가 지원되지 않는다**는 뜻이지 채널이 중단되었다는 뜻이 아닙니다 — `1k` / `2k`로 다시 전환하십시오.
</Info>

### `n` (호출당 이미지 수)

**1-10**을 허용합니다. 반환되는 `data` 배열 길이는 `n`와 같으며, 각 이미지는 과금됩니다. `0`은 조용히 `1`로 처리되며, `11` 이상이면 400을 반환합니다.

## 모범 사례

<Steps>
  <Step title="우선 결정합니다: 생성입니까, 편집입니까?">
    참조 이미지가 없으면 → `/v1/images/generations`. 참조 이미지가 하나라도 있으면, 픽셀 하나만 수정하는 경우라도 → `/v1/images/edits`. 잘못된 엔드포인트를 선택해도 오류는 발생하지 않고, 예상치 못한 이미지가 나올 뿐입니다.
  </Step>

  <Step title="클라이언트 타임아웃을 360초로 설정합니다">
    이미지 API는 동기식입니다. 2K는 1장당 15-17초가 걸리며, 피크 시간이나 콜드 스타트 시 더 길어질 수 있습니다. 60초 타임아웃은 여전히 과금되는 요청에서 불필요한 실패를 유발합니다.
  </Step>

  <Step title="구도는 prompt가 아니라 aspect_ratio로 제어합니다">
    이 파라미터는 실제로 동작하므로, prompt에서 “가로 구도”를 요청하는 것보다 `aspect_ratio: "16:9"`이 훨씬 더 신뢰할 수 있습니다.
  </Step>

  <Step title="대역폭에 따라 해상도 등급을 선택합니다">
    2K는 이미지당 5-6 MB의 무손실 PNG이며, 1K는 220-300 KB의 JPEG입니다 — 대략 20배 차이입니다. 모바일이나 대량 전송에는 1K를 권장합니다. 두 등급의 비용은 같으므로, 선택은 순전히 품질 대 대역폭의 문제입니다.
  </Step>

  <Step title="편집할 때 «다른 모든 것은 그대로 유지»라고 말합니다">
    "스카프를 빨간색으로 바꾸고, 다른 모든 것은 완전히 동일하게 유지해 주세요" 같은 지시는 매우 잘 작동합니다 — 모델이 이 제약을 엄격하게 따르며 이미지의 나머지 부분을 보존합니다.
  </Step>

  <Step title="융합할 때는 이미지를 명시적으로 참조합니다">
    `image[]` 업로드 순서가 "이미지 1 / 이미지 2 / 이미지 3"의 의미입니다. "이미지 1의 주체를 이미지 2의 장면에 넣어 주세요"라고 쓰는 것이 모델에 맡겨 추측하게 하는 것보다 훨씬 더 신뢰할 수 있습니다.
  </Step>

  <Step title="재현성을 위해 seed에 의존하지 마십시오">
    이 계열은 `seed`을 지원하지 않습니다. 같은 prompt라도 호출마다 다른 결과가 나옵니다. 다시 생성될 것을 기대하기보다 유지하려는 이미지를 보관하십시오.
  </Step>

  <Step title="배치 작업은 그냥 동시 실행으로 처리합니다">
    동시 실행 수 제한은 없습니다 — **100 RPM도 여유롭게 처리됩니다**. 충분한 채널 용량이 있습니다. 직렬 큐를 만들거나 추가 쿼터를 요청할 필요가 없습니다.
  </Step>
</Steps>

## 오류 코드 및 재시도

| HTTP  | 코드                          | 의미                                    | 권장 처리                                             |
| ----- | --------------------------- | ------------------------------------- | ------------------------------------------------- |
| `400` | `invalid_image_request`     | 편집 엔드포인트가 multipart 대신 JSON을 수신했습니다   | `multipart/form-data` 업로드로 전환하십시오. 재시도하지 마십시오     |
| `400` | `invalid_request`           | 잘못된 매개변수 **또는** prompt가 모더레이션에 의해 차단됨 | 두 경우 모두 같은 코드입니다 — 먼저 매개변수를 확인한 다음 prompt를 수정하십시오 |
| `415` | —                           | 편집 엔드포인트에서 지원되지 않는 파일 필드 이름           | 필드 이름을 `image` 또는 `image[]`로 바꾸십시오                |
| `429` | —                           | 요청 제한 초과 또는 잔액 부족                     | 지수 백오프를 사용하고 계정 잔액을 확인하십시오                        |
| `503` | `model_service_unavailable` | 지원되지 않는 매개변수 티어(예: `resolution: 4k`)  | **장애가 아닙니다** — `1k` / `2k`로 되돌리고 재시도하지 마십시오       |
| `503` | —                           | 현재 그룹에서 사용할 수 있는 채널이 없습니다             | 토큰의 그룹 설정을 확인하십시오. 위의 그룹 설정을 참조하십시오               |

<Info>
  **클라이언트 지침**: `400`와 `415`은 결정적입니다 — 재시도는 소용이 없으므로 대신 알림을 보내십시오. `429`와 네트워크 계층 타임아웃만 재시도할 가치가 있으며, 지수 백오프를 사용하고 최대 3회 시도하십시오.

  참고로 `400 invalid_request`는 “bad parameter”와 “content blocked”를 모두 포함하며, **응답 본문으로는 둘을 구분할 수 없습니다**. 실용적인 휴리스틱은 지연 시간입니다. 모더레이션 차단은 약 5\~6초 만에 반환되며 — 성공적인 생성(\~9초)보다 빠릅니다 — 차단이 생성이 시작되기 전에 발생하기 때문입니다.
</Info>

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="벤더 문서에는 JSON으로 표시되는데, /v1/images/edits에 JSON을 보내면 왜 400이 반환됩니까?">
    APIYI 게이트웨이의 편집 엔드포인트는 `multipart/form-data`만 허용하는 반면, 상위 벤더 문서는 공개 이미지 URL이 포함된 JSON 본문을 설명합니다. 둘은 다릅니다 — 이 사이트의 문서를 따르십시오.

    올바른 형식은 파일 업로드입니다:

    ```bash theme={null}
    curl -X POST "https://api.apiyi.com/v1/images/edits" \
      -H "Authorization: Bearer sk-your-api-key" \
      -F "model=grok-imagine-image" \
      -F "prompt=Change the scarf to red, keep everything else the same" \
      -F "image=@photo.jpg"
    ```

    장점은 이미지 호스팅이 필요 없다는 점입니다 — 로컬 파일을 직접 업로드하면 되므로 공개 URL을 준비하는 것보다 간단합니다. 전체 예시는 [이미지 편집 API](/ko/api-capabilities/grok-imagine-image/image-edit)에서 확인하십시오.
  </Accordion>

  <Accordion title="텍스트-이미지에 참조 이미지를 보냈더니 200이 왔는데, 결과가 무관한 이유는 무엇입니까?">
    그것은 예상된 동작이며, 이 모델에서 가장 흔한 함정입니다: `/v1/images/generations`은 `image` / `image_url` / `images`를 **조용히 무시하고**, prompt만으로 생성하며, **과금은 평소와 같이 됩니다**.

    오류 신호가 없으므로 "편집이 고장 났다"고 결론내리기 쉽습니다. **참조 이미지를 사용하는 모든 워크플로는 `/v1/images/edits`을 사용해야 합니다.**
  </Accordion>

  <Accordion title="편집 엔드포인트에서 resolution / aspect_ratio가 아무런 영향을 주지 않는 이유는 무엇입니까?">
    편집된 출력 크기는 **입력 참조 이미지**를 따릅니다: 1280x720으로 넣으면 1280x720이 출력되고, 1024x1024로 넣으면 1024x1024가 출력됩니다. 여기서 `resolution`이나 `aspect_ratio`을 전달해도 오류는 발생하지 않지만 아무런 동작도 하지 않습니다.

    출력 크기를 변경하려면 업로드하기 전에 참조 이미지를 자르거나 크기를 조정하십시오.
  </Accordion>

  <Accordion title="응답에 revised_prompt가 없는 이유는 무엇입니까?">
    이 계열은 `revised_prompt`도 반환하지 않으며, `respect_moderation` 또는 `model` 같은 필드도 반환하지 않습니다. 각 `data[]` 항목에는 `response_format`에 따라 **`url` 또는 `b64_json` 중 하나만** 포함되며, 둘 다 포함되지는 않습니다.

    응답을 파싱할 때 이러한 필드가 존재한다고 가정하지 마십시오.
  </Accordion>

  <Accordion title="usage의 token 개수로 과금을 정산할 수 있습니까?">
    **아닙니다.** `usage.prompt_tokens`은 실제 prompt 길이와 관계없이 항상 `1000 x n`입니다 — 이는 자리표시자입니다.

    이 계열은 이미지당 정액 요금으로 요청별 과금됩니다. 실제 청구 금액은 APIYI 콘솔의 과금 기록을 사용하십시오.
  </Accordion>

  <Accordion title="왜 1K는 JPEG인데 2K는 PNG입니까? 크기 차이가 매우 큽니다">
    그것은 상위 서비스 동작입니다: `resolution: 1k`는 JPEG(\~220-300 KB)를 반환하고 `resolution: 2k`는 무손실 PNG(\~5-6 MB)를 반환하여 대략 20배 차이가 납니다.

    URL 확장자, HTTP `Content-Type`, 실제 바이트는 서로 일치하므로 `Content-Type`에 따라 안전하게 분기할 수 있습니다.

    대역폭에 민감한 상황(모바일, 대량 전송)에서는 `1k`을 선호하십시오 — 두 등급의 비용은 같으므로 결정은 순전히 품질에 관한 문제입니다.
  </Accordion>

  <Accordion title="resolution: 4k에서 503이 반환되는데 — 채널이 다운된 것입니까?">
    **아닙니다.** `4k`은 이 계열에서 지원되는 등급이 아니며, 게이트웨이는 `503 model_service_unavailable`를 반환합니다. 코드는 장애처럼 보이지만 실제로는 파라미터 문제이므로 **재시도해도 도움이 되지 않습니다** — `1k` 또는 `2k`으로 다시 전환하십시오.

    지원되는 것은 `1k`과 `2k`뿐입니다.
  </Accordion>

  <Accordion title="잘못된 파라미터가 오류 대신 잘못된 이미지를 생성하는 이유는 무엇입니까?">
    이 계열의 검증은 관대합니다: 잘못된 `aspect_ratio`(예: `5:7`), `resolution`(예: `1K`, `1024x1024`) 및 `response_format`(예: `base64`)는 모두 **조용히 기본값으로 되돌아가며** 400 대신 여전히 이미지를 반환합니다.

    따라서 출력이 기대와 다르다면 **먼저 파라미터 철자를 확인하십시오** — 특히 `resolution` 값은 소문자 `1k` / `2k`입니다.
  </Accordion>

  <Accordion title="한 번의 호출로 몇 개의 이미지를 생성할 수 있습니까?">
    `n`은 **1-10**을 허용하며, 반환되는 `data` 배열의 길이는 `n`와 같습니다. 각 이미지는 **과금됩니다**.

    `0`은 조용히 `1`로 처리되며, `11` 이상은 `400 invalid_request`을 반환합니다.
  </Accordion>

  <Accordion title="seed 기반 재현성이 지원됩니까?">
    **아닙니다.** `seed`를 전달해도 오류는 발생하지 않지만 효과는 없습니다 — 동일한 prompt와 동일한 `seed`라도 호출마다 다른 이미지가 반환됩니다.

    다시 생성하려 하기보다, 다시 사용할 필요가 있는 이미지는 저장해 두십시오.
  </Accordion>

  <Accordion title="공식 OpenAI SDK로 이것을 호출할 수 있습니까?">
    예. 두 엔드포인트는 OpenAI 이미지 API와 호환됩니다 — `base_url`을 `https://api.apiyi.com/v1`에 지정하기만 하면 됩니다:

    ```python theme={null}
    from openai import OpenAI
    client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")

    resp = client.images.generate(
        model="grok-imagine-image",
        prompt="a red wooden boat on an alpine lake at dawn",
        extra_body={"aspect_ratio": "16:9", "resolution": "1k"}
    )
    ```

    `aspect_ratio`와 `resolution`은 표준 OpenAI SDK 필드가 아니므로 `extra_body`를 통해 전달하십시오.
  </Accordion>

  <Accordion title="동시 실행 수 제한이 있습니까? 배치 생성이 제한됩니까?">
    **동시 실행 수 제한은 없습니다.** **429도 없고 큐 거부도 없는 상태에서 100 RPM에서도 여유 있게 측정되었습니다.** 충분한 채널 용량을 바탕으로 운영되므로, 직렬 큐를 만들거나 추가 쿼터를 요청하지 말고 동시에 호출하십시오.

    실제로 중요한 것은 \*\*`timeout`\*\*입니다: 이미지 API는 동기식이므로, 정상적으로 처리 중이면서도 여전히 과금되는 요청을 끊지 않도록 클라이언트 timeout을 **360초**로 설정하십시오.
  </Accordion>

  <Accordion title="콘텐츠 검열은 어떻게 동작하며, 차단은 어떻게 감지합니까?">
    이 계열에는 콘텐츠 검열이 적용됩니다. 차단된 요청은 파라미터 오류와 **정확히 동일한 오류 코드와 메시지**를 사용하여 `400 invalid_request`을 반환하므로, 응답 본문만으로는 구분할 수 없습니다.

    실용적인 휴리스틱은 **지연 시간**입니다: 검열 차단은 약 5-6초 만에 반환되며(차단이 생성보다 먼저 발생함), 성공적인 이미지는 약 9초가 걸립니다. 검열 결과에는 어느 정도 무작위성도 있으므로 경계선 콘텐츠는 재시도마다 동일하게 동작하지 않을 수 있습니다 — **한 번의 시도만으로 결론을 내리지 마십시오**.

    파라미터가 올바르다고 확인되었는데도 400이 계속된다면, prompt가 검열을 유발했을 가능성이 가장 큽니다. 표현을 수정하십시오.
  </Accordion>

  <Accordion title="/v1/chat/completions을 통해 이미지를 생성할 수 있습니까?">
    예, 하지만 **권장 경로는 아닙니다**. 해당 엔드포인트는 표준 채팅 구조를 반환하며, 그 `content`은 markdown 이미지 링크입니다:

    ```text theme={null}
    ![image](https://apac.ossforai.com/...)
    ```

    Chatbox나 LobeChat 같은 대화형 클라이언트에 적합합니다. 프로그램 통합에는 **Images API를 사용하십시오** (`/v1/images/generations` 및 `/v1/images/edits`) — 더 풍부한 파라미터, 더 안정적인 응답 형식, 그리고 이 문서와의 일관성을 제공합니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [Grok Imagine 2 텍스트-투-이미지 API](/ko/api-capabilities/grok-imagine-image/text-to-image) - 플레이그라운드가 포함된 엔드포인트 레퍼런스
* [Grok Imagine 2 이미지 편집 API](/ko/api-capabilities/grok-imagine-image/image-edit) - 편집 및 다중 이미지 융합 레퍼런스
* [Grok 모델 가이드](/ko/api-capabilities/grok/overview) - xAI 텍스트 모델
* [이미지 API 모범 사례](/ko/api-capabilities/image-api-best-practices) - 타임아웃, 연결 끊김, 압축
* [API 매뉴얼](/ko/api-manual)
* [충전 프로모션](/ko/faq/recharge-promotions)