> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkBuddy-이미지 생성

> 사용자 지정 커넥터로 WorkBuddy에 GravitexAI 이미지 생성 및 편집 모델을 연결하는 가이드

macOS와 Windows에 적용됩니다. 앱을 완전히 종료하는 방법 외에는 절차가 같습니다. 사용자 지정 커넥터를 통해 텍스트로 이미지 생성, 참고 이미지 편집, 같은 주제의 여러 모델 결과 비교를 할 수 있습니다.

## 1. 기능 소개

한 번의 JSON 설정으로 여러 이미지 모델을 등록하며 모델마다 별도 계정을 만들 필요가 없습니다.

| 기능 | 설명 |
| - | - |
| 하나의 키로 여러 모델 | GravitexAI 키 하나로 GPT, Gemini 등 이미지 모델 사용 |
| 로컬 키 저장 | API 키를 포함한 커넥터 설정은 로컬에 저장되며 클라우드에 업로드되지 않음 |
| 짧은 이름 | gemini-pro 같은 이름을 지정하고 대화에서 요청 |
| 모델 비교 | 같은 주제를 여러 모델로 생성해 비교 |
| 사용량 과금 | 이미지 API 비용은 GravitexAI에 청구되며 WorkBuddy 크레딧/요금제 할당량을 소모하지 않음 |

## 2. 환경 요구 사항

* Windows 10 이상. Windows 7, 8, 8.1 미지원.
* macOS 12 Monterey 이상.

> [!TIP]
>
> 이 요구 사항을 충족하지 않는 시스템에서는 WorkBuddy를 실행할 수 없습니다.

## 3. 사전 조건

* WorkBuddy 설치.
* [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 API 키 생성(`sk-xxxxxxxxxx`).
* **Windows:** npx 사용을 위해 [Node.js LTS](https://nodejs.org/)를 기본 옵션으로 설치.

## 4. 빠른 시작

### 1단계: API 키 생성

[GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 토큰을 만들고 이름을 지정해 저장한 뒤 `sk-`로 시작하는 키를 복사합니다.

### 2단계: 사용자 지정 커넥터 열기

왼쪽 **전문가 · 스킬 · 커넥터**에서 **커넥터** 탭을 선택하고 오른쪽 위 **사용자 지정 커넥터**를 누릅니다. 스크린샷은 중국어 UI입니다.

![WorkBuddy 사용자 지정 커넥터 위치](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/workbuddy-image-generation-1.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=51602bc7ae5132f1a9b2c39f57e38e69)

### 3단계: JSON 붙여넣기

아래 전체 JSON을 설정 창에 붙여넣고 **모든 `sk-your-api-key`를 실제 키로 바꿉니다**.

```json theme={null}
{
  "mcpServers": {
    "gpt-image-2": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gpt-image-2"
      }
    },
    "gpt-flare": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gpt-image-2.5-flare"
      }
    },
    "gpt-sunburst": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gpt-image-2.5-sunburst"
      }
    },
    "gpt-image-1": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gpt-image-1"
      }
    },
    "gemini-pro": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gemini-3-pro-image"
      }
    },
    "gemini-flash": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gemini-3.1-flash-image"
      }
    },
    "gemini-2.5-flash": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gemini-2.5-flash-image"
      }
    },
    "gemini-flash-lite": {
      "command": "npx",
      "args": ["-y", "@junjun-org/proxy-gpt-image@latest"],
      "env": {
        "OPENAI_BASE_URL": "https://api.gravitex.ai/v1",
        "OPENAI_API_KEY": "sk-your-api-key",
        "IMAGE_MODEL": "gemini-3.1-flash-lite-image"
      }
    }
  }
}
```

> [!NOTE]
>
> 항목 이름(gpt-flare 등)은 자유롭게 지정할 수 있으며 WorkBuddy의 커넥터 이름이 됩니다. Windows는 먼저 Node.js LTS를 설치하고 command에 npx를 입력하세요. npx.cmd로 바꾸지 마세요.

### 4단계: 재시작 및 신뢰

WorkBuddy를 완전히 종료하고 다시 엽니다.

* macOS: `Cmd + Q`. 창만 닫으면 종료되지 않습니다.
* Windows: 작업 표시줄/트레이에서 종료하거나 `Ctrl + Shift + Esc`로 작업 관리자를 열어 프로세스 종료를 확인합니다.

**커넥터 → 사용자 지정 커넥터**로 돌아가 필요한 항목에 \*\*신뢰(Trust)\*\*를 선택합니다. 커넥터마다 npx 프로세스가 실행되므로 자주 쓰는 2\~3개부터 신뢰하고 나머지는 필요할 때 켜는 것이 좋습니다.

> [!WARNING]
>
> 창만 닫지 말고 프로세스를 완전히 종료하세요. 완전 재시작 전에는 새 커넥터가 적용되지 않을 수 있습니다.

### 5단계: 사용 시작

작업 화면의 **+ → 커넥터**에서 사용할 모델을 선택합니다. 아래 일상 사용 및 프롬프트 예시를 참고하세요.

## 5. 모델 참고표

| 커넥터 이름 | 모델 ID | 용도 |
| - | - | - |
| `gpt-image-2` | `gpt-image-2` | GPT 범용 주력 |
| `gpt-flare` | `gpt-image-2.5-flare` | 최신 GPT 변형 |
| `gpt-sunburst` | `gpt-image-2.5-sunburst` | 다른 스타일의 GPT 변형 |
| `gpt-image-1` | `gpt-image-1` | 이전 GPT 세대 |
| `gemini-pro` | `gemini-3-pro-image` | 고성능 Gemini |
| `gemini-flash` | `gemini-3.1-flash-image` | 빠른 모델 |
| `gemini-2.5-flash` | `gemini-2.5-flash-image` | 이전 빠른 모델 |
| `gemini-flash-lite` | `gemini-3.1-flash-lite-image` | 이 목록의 최저 비용 옵션 |

> [!NOTE]
>
> 정확한 ID는 [GravitexAI 모델 목록](https://maas.gravitex.ai/#/api-models)을 따릅니다. 표에 없는 seedream-5-0-260128 등을 임시로 쓰려면 대화에서 전체 ID를 말해 기본 모델을 해당 호출에만 재정의할 수 있습니다.

## 6. 일상 사용

* **작업 기본값:** **+ → 커넥터**에서 한 항목을 선택합니다.
* **짧은 이름으로 전환:** “flash로 그려 줘”, “pro로 한 장 더”처럼 요청합니다.
* **미등록 모델 임시 사용:** seedream-5-0-260128처럼 전체 ID를 지정하면 설정 변경 없이 호출 기본값을 바꿀 수 있습니다.

저장된 기본 모델을 바꾸려면 커넥터를 삭제하고 `IMAGE_MODEL`을 변경한 JSON으로 다시 추가한 뒤 앱을 완전히 재시작합니다. 커넥터는 제자리 편집을 지원하지 않습니다.

텍스트로 이미지를 생성할 때는 원하는 장면을 설명하고, 이미지를 편집할 때는 참고 이미지와 변경 내용을 함께 제공합니다.

## 7. 프롬프트 예시

### 선택한 기본 모델로 이미지 생성

> 1024x1024 크기의 평면 스타일 빨간 사과 아이콘을 그려 줘.

### 모델 지정

> gemini-pro로 눈 덮인 산의 일출을 그려 줘.

> flash로 같은 장면을 한 번 더 그려 줘.

> gpt-flare로 이 이미지를 수채화로 바꿔 줘.

### 기존 이미지 편집

> 바탕화면의 lamb-grazing.png를 참고해 배경을 빨간색으로 바꿔 줘.

> 나머지는 그대로 두고 낮을 밤으로 바꿔 줘.

### 크기와 품질

> 1536x1024 가로 풍경을 low 품질로 빠르게 만들어 줘.

> 1024x1536 세로 휴대폰 배경화면을 high 품질로 만들어 줘.

크기: `1024x1024`(정사각), `1536x1024`(가로), `1024x1536`(세로). 품질: `low`(빠름/경제적), `auto`(기본), `high`(정밀, 약 1\~2분).

### 모델 비교

> gpt-image-2와 gemini-pro로 같은 주제를 각각 한 장씩 그려 비교해 줘.

## 8. 문제 해결

> [accordion] 설정한 커넥터가 보이지 않음
>
> JSON의 자리표시자 키를 모두 바꿨는지 확인하고 앱을 완전히 재시작하세요. macOS는 Cmd+Q, Windows는 작업 관리자에서 종료를 확인합니다.

> [accordion] 401 응답
>
> 키가 sk-로 시작하고 공백이 없는지 확인하세요. GravitexAI 콘솔에서 토큰 활성 상태와 잔액을 확인합니다. 잔액 부족도 401을 반환할 수 있습니다.

> [accordion] 이미지 편집 시 404
>
> 일부 게이트웨이는 edits 경로가 달라 editPath 설정이 필요할 수 있습니다. 모델의 편집 엔드포인트와 커넥터의 해당 env 설정을 확인하세요.

> [accordion] Windows에서 npx를 찾을 수 없음
>
> Node.js LTS를 설치하고 PATH에 포함되어 있는지 확인한 뒤 WorkBuddy를 재시작합니다.

> [accordion] 이미지 생성이 WorkBuddy 크레딧을 소모하나요?
>
> 이미지 API 비용은 GravitexAI 계정으로 결제되며 WorkBuddy 크레딧이나 요금제 할당량을 소모하지 않습니다. GravitexAI 잔액과 사용량을 확인하세요.

> [accordion] 기본 모델을 바로 편집할 수 있나요?
>
> 커넥터를 삭제하고 IMAGE\_MODEL 값을 바꾼 JSON으로 다시 추가한 다음 완전히 재시작합니다.

## 9. 관련 자료

* [WorkBuddy 공식 사이트](https://www.workbuddy.cn)
* [GravitexAI 키 관리](https://maas.gravitex.ai/#/api-keys)
* [GravitexAI 모델 목록](https://maas.gravitex.ai/#/api-models)
* [WorkBuddy 대화 모델 설정](https://docs.gravitex.ai/ko/integrations/workbuddy.md)


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