---
read_when:
    - 에이전트를 통해 이미지를 생성할 때
    - 이미지 생성 공급자 및 모델을 구성할 때
    - '`image_generate` 도구 매개변수를 이해할 때'
summary: 구성된 공급자(OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra)를 사용해 이미지를 생성하고 편집합니다
title: 이미지 생성
x-i18n:
    generated_at: "2026-04-07T06:02:06Z"
    model: gpt-5.4
    provider: openai
    source_hash: 8f7303c199d46e63e88f5f9567478a1025631afb03cb35f44344c12370365e57
    source_path: tools/image-generation.md
    workflow: 15
---

# 이미지 생성

`image_generate` 도구를 사용하면 에이전트가 구성된 공급자를 사용해 이미지를 생성하고 편집할 수 있습니다. 생성된 이미지는 에이전트의 응답에 미디어 첨부파일로 자동 전달됩니다.

<Note>
이 도구는 하나 이상의 이미지 생성 공급자를 사용할 수 있을 때만 표시됩니다. 에이전트의 도구에 `image_generate`가 보이지 않으면 `agents.defaults.imageGenerationModel`을 구성하거나 공급자 API 키를 설정하세요.
</Note>

## 빠른 시작

1. 하나 이상의 공급자에 대해 API 키를 설정합니다(예: `OPENAI_API_KEY` 또는 `GEMINI_API_KEY`).
2. 필요하면 선호하는 모델을 설정합니다.

```json5
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
      },
    },
  },
}
```

3. 에이전트에게 요청합니다: _"친근한 바닷가재 마스코트 이미지를 생성해 줘."_

에이전트는 `image_generate`를 자동으로 호출합니다. 도구 허용 목록은 필요하지 않습니다. 공급자를 사용할 수 있으면 기본적으로 활성화됩니다.

## 지원되는 공급자

| 공급자 | 기본 모델                       | 편집 지원                           | API 키                                                |
| ------ | ------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| OpenAI | `gpt-image-1`                   | 예(최대 5개 이미지)                 | `OPENAI_API_KEY`                                      |
| Google | `gemini-3.1-flash-image-preview` | 예                                  | `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`                |
| fal    | `fal-ai/flux/dev`               | 예                                  | `FAL_KEY`                                             |
| MiniMax | `image-01`                     | 예(주제 참조)                       | `MINIMAX_API_KEY` 또는 MiniMax OAuth (`minimax-portal`) |
| ComfyUI | `workflow`                     | 예(1개 이미지, 워크플로 구성 기반)  | 클라우드용 `COMFY_API_KEY` 또는 `COMFY_CLOUD_API_KEY` |
| Vydra  | `grok-imagine`                  | 아니요                              | `VYDRA_API_KEY`                                       |

런타임에 사용 가능한 공급자와 모델을 확인하려면 `action: "list"`를 사용하세요.

```
/tool image_generate action=list
```

## 도구 매개변수

| 매개변수      | 유형     | 설명                                                                                  |
| ------------- | -------- | ------------------------------------------------------------------------------------- |
| `prompt`      | string   | 이미지 생성 프롬프트(`action: "generate"`일 때 필수)                                  |
| `action`      | string   | 공급자를 확인하기 위한 `"generate"`(기본값) 또는 `"list"`                             |
| `model`       | string   | 공급자/모델 재정의. 예: `openai/gpt-image-1`                                          |
| `image`       | string   | 편집 모드를 위한 단일 참조 이미지 경로 또는 URL                                      |
| `images`      | string[] | 편집 모드를 위한 여러 참조 이미지(최대 5개)                                          |
| `size`        | string   | 크기 힌트: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024`           |
| `aspectRatio` | string   | 화면비: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`     |
| `resolution`  | string   | 해상도 힌트: `1K`, `2K`, 또는 `4K`                                                   |
| `count`       | number   | 생성할 이미지 수(1–4)                                                                |
| `filename`    | string   | 출력 파일명 힌트                                                                      |

모든 공급자가 모든 매개변수를 지원하는 것은 아닙니다. 폴백 공급자가 정확히 요청한 옵션 대신 근접한 기하 옵션을 지원하는 경우, OpenClaw는 제출 전에 가장 가까운 지원 크기, 화면비 또는 해상도로 다시 매핑합니다. 실제로 지원되지 않는 재정의는 여전히 도구 결과에 보고됩니다.

도구 결과는 적용된 설정을 보고합니다. 공급자 폴백 중 OpenClaw가 기하 설정을 다시 매핑하면 반환되는 `size`, `aspectRatio`, `resolution` 값은 실제로 전송된 값을 반영하며, `details.normalization`은 요청값에서 적용값으로의 변환을 담습니다.

## 구성

### 모델 선택

```json5
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"],
      },
    },
  },
}
```

### 공급자 선택 순서

이미지를 생성할 때 OpenClaw는 다음 순서로 공급자를 시도합니다.

1. 도구 호출의 **`model` 매개변수**(에이전트가 지정한 경우)
2. 구성의 **`imageGenerationModel.primary`**
3. 순서대로 **`imageGenerationModel.fallbacks`**
4. **자동 감지** — 인증 기반 공급자 기본값만 사용:
   - 현재 기본 공급자를 먼저
   - 나머지 등록된 이미지 생성 공급자를 공급자 ID 순서대로

공급자가 실패하면(인증 오류, 속도 제한 등) 다음 후보를 자동으로 시도합니다. 모두 실패하면 오류에 각 시도의 세부 정보가 포함됩니다.

참고:

- 자동 감지는 인증 인식 방식입니다. OpenClaw가 실제로 해당 공급자를 인증할 수 있을 때만 공급자 기본값이 후보 목록에 들어갑니다.
- 자동 감지는 기본적으로 활성화되어 있습니다. 이미지 생성이 명시적인 `model`, `primary`, `fallbacks` 항목만 사용하도록 하려면 `agents.defaults.mediaGenerationAutoProviderFallback: false`로 설정하세요.
- 현재 등록된 공급자, 해당 기본 모델, 인증 환경 변수 힌트를 확인하려면 `action: "list"`를 사용하세요.

### 이미지 편집

OpenAI, Google, fal, MiniMax, ComfyUI는 참조 이미지 편집을 지원합니다. 참조 이미지 경로 또는 URL을 전달하세요.

```
"이 사진을 수채화 버전으로 생성해 줘" + image: "/path/to/photo.jpg"
```

OpenAI와 Google은 `images` 매개변수를 통해 최대 5개의 참조 이미지를 지원합니다. fal, MiniMax, ComfyUI는 1개를 지원합니다.

MiniMax 이미지 생성은 번들된 두 MiniMax 인증 경로 모두에서 사용할 수 있습니다.

- API 키 설정용 `minimax/image-01`
- OAuth 설정용 `minimax-portal/image-01`

## 공급자 기능

| 기능                  | OpenAI            | Google             | fal                | MiniMax                    | ComfyUI                           | Vydra  |
| --------------------- | ----------------- | ------------------ | ------------------ | -------------------------- | --------------------------------- | ------ |
| 생성                  | 예(최대 4개)      | 예(최대 4개)       | 예(최대 4개)       | 예(최대 9개)               | 예(워크플로 정의 출력)            | 예(1개) |
| 편집/참조             | 예(최대 5개 이미지) | 예(최대 5개 이미지) | 예(1개 이미지)    | 예(1개 이미지, 주제 참조)  | 예(1개 이미지, 워크플로 구성 기반) | 아니요 |
| 크기 제어             | 예                | 예                 | 예                 | 아니요                     | 아니요                            | 아니요 |
| 화면비                | 아니요            | 예                 | 예(생성만)         | 예                         | 아니요                            | 아니요 |
| 해상도(1K/2K/4K)      | 아니요            | 예                 | 예                 | 아니요                     | 아니요                            | 아니요 |

## 관련 문서

- [도구 개요](/ko/tools) — 사용 가능한 모든 에이전트 도구
- [fal](/ko/providers/fal) — fal 이미지 및 비디오 공급자 설정
- [ComfyUI](/ko/providers/comfy) — 로컬 ComfyUI 및 Comfy Cloud 워크플로 설정
- [Google (Gemini)](/ko/providers/google) — Gemini 이미지 공급자 설정
- [MiniMax](/ko/providers/minimax) — MiniMax 이미지 공급자 설정
- [OpenAI](/ko/providers/openai) — OpenAI Images 공급자 설정
- [Vydra](/ko/providers/vydra) — Vydra 이미지, 비디오, 음성 설정
- [구성 참조](/ko/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 구성
- [모델](/ko/concepts/models) — 모델 구성 및 장애 조치
