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

# 투명 배경 이미지

> /image/generate, /image/edit, /image/multi-edit의 transparent_background 또는 OpenAI 호환 endpoint의 background: transparent를 사용해 실제 알파 채널이 포함된 PNG 또는 WebP 이미지를 생성하고 편집하세요.

Venice 이미지 API는 흰색이나 체커보드를 덧칠한 배경 대신 실제 알파 채널이 포함된 이미지를 반환할 수 있습니다. 모델이 처음부터 투명도를 고려해 피사체를 구성하므로, 가장자리, 그림자, 반투명 영역(유리, 머리카락, 연기)이 딱딱한 마스크가 아닌 픽셀 단위 알파 값을 가집니다.

이는 완성된 불투명 이미지를 받아 사후에 전경을 분할하는 `/image/background-remove`와는 다릅니다. 어차피 자산을 생성하거나 편집할 예정이라면 네이티브 투명도를 사용하고, 불투명 이미지만 가지고 있다면 배경 제거를 사용하세요.

<Frame as="div" caption="gpt-image-2-5-flare에서 동일한 prompt와 seed를 사용한 결과. 왼쪽: 기본 출력. 오른쪽: transparent_background: true, 체커보드 위에 표시. 드롭 섀도가 부분 알파로 보존됩니다.">
  <img src="https://mintcdn.com/veniceai/W3Pe6eTTsq9YXpsg/images/guides/transparent-backgrounds/before-after.webp?fit=max&auto=format&n=W3Pe6eTTsq9YXpsg&q=85&s=c9be8661231052a405dc949687f9f5ee" alt="나란히 비교: 불투명한 스튜디오 배경에 렌더링된 아이스티 잔과, 체커보드 위에 표시된 투명 배경의 같은 잔" width="1192" height="518" data-path="images/guides/transparent-backgrounds/before-after.webp" />
</Frame>

## 필요한 것

| 요구 사항 | 세부 내용 |
| - | - |
| 모델 | `GET /models` constraints에 `supportsTransparentBackground: true`가 표시된 모델. 현재 `gpt-image-1-5`, `gpt-image-2-5-flare`, `gpt-image-2-5-sunburst`(편집 endpoint의 경우 각각의 `-edit` 변형) |
| 출력 포맷 | `png` 또는 `webp`. JPEG에는 알파 채널이 없으므로 `jpeg`는 거부됩니다 |
| 파라미터 | `/image/generate`, `/image/edit`, `/image/multi-edit`에서는 `transparent_background: true`. `/images/generations`에서는 `background: "transparent"` |

그 외의 경우에는 추론이 실행되기 전에 `400`이 반환되므로, 거부된 요청에는 비용이 청구되지 않습니다.

## 1단계: 투명 이미지 생성

`/image/generate`는 네이티브 endpoint입니다. `format`을 `png` 또는 `webp`로, `transparent_background`를 `true`로 설정하세요.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o sticker.png \
  -d '{
    "model": "gpt-image-2-5-flare",
    "prompt": "A die-cut sticker of a cartoon rocket ship, bold outlines, flat colors, no background",
    "format": "png",
    "transparent_background": true,
    "quality": "low",
    "return_binary": true
  }'
```

응답은 RGBA 픽셀 레이아웃을 가진 `content-type: image/png`입니다. `return_binary`를 사용하지 않으면 `images[0]`에 base64 문자열이 담긴 일반 JSON 응답을 받습니다.

`format`의 기본값은 `webp`이며 이 역시 알파를 지원하므로, `format`을 생략해도 동작합니다. 명시적으로 `"format": "jpeg"`를 지정한 경우에만 실패합니다.

<Tip>
  플래그를 설정하는 것과 함께 prompt에도 "no background" 또는 "isolated on transparent background"라고 명시하세요. 플래그는 알파 채널을 보장하고, prompt는 모델이 피사체의 경계 상자 안에서 불투명하게 남을 바닥, 테이블, 배경막을 그리지 않도록 유도합니다.
</Tip>

## 2단계: 알파 채널 확인

파일 확장자를 믿지 마세요. 픽셀 모드를 확인하고 알파 분포를 살펴서, 배경이 평탄화된 흰색 채움이 아니라 실제로 투명한지 확인하세요.

```python theme={"system"}
from PIL import Image

im = Image.open("sticker.png")
print(im.format, im.mode, im.size)  # PNG RGBA (1024, 1024)

alpha = im.getchannel("A")
hist = alpha.histogram()
total = sum(hist)
print(f"fully transparent: {100 * hist[0] / total:.1f}%")
print(f"partially transparent: {100 * sum(hist[1:255]) / total:.1f}%")
print("subject bbox:", alpha.getbbox())
```

올바른 결과에서는 픽셀의 상당 부분이 알파 `0`(배경)이고, 가장자리를 따라 부분 값의 띠(안티앨리어싱과 부드러운 그림자)가 있으며, 피사체의 경계 상자가 캔버스보다 작습니다. `im.mode`가 `RGB`이거나 투명 비율이 `0%`라면 파이프라인 어딘가에서 알파 채널이 손실된 것이며, 대개 알파를 버리는 리사이즈 또는 재인코딩 단계가 원인입니다.

<Frame as="div" caption="위 이미지의 알파 채널만 분리한 모습. 잔 아래의 그림자가 흰색에서 검은색으로 급격히 바뀌지 않고 수십 단계의 회색으로 서서히 사라지며, 이는 임의의 배경 위에 합성할 때 바람직한 형태입니다.">
  <img src="https://mintcdn.com/veniceai/W3Pe6eTTsq9YXpsg/images/guides/transparent-backgrounds/alpha-channel.webp?fit=max&auto=format&n=W3Pe6eTTsq9YXpsg&q=85&s=e58c7a0a0d4e6aebb06a0341871731c5" alt="세 개의 패널: 체커보드 위의 투명 이미지, 그레이스케일 마스크로 표시한 알파 채널, 부드러운 그라데이션을 보여주는 그림자 가장자리 확대 이미지" width="1776" height="607" data-path="images/guides/transparent-backgrounds/alpha-channel.webp" />
</Frame>

<Note>
  GPT Image 모델은 현재 불투명 영역을 `255`가 아닌 알파 `252`–`254`로 반환합니다. 시각적으로는 구별할 수 없지만, 피사체를 찾기 위해 `== 255`로 임계값을 설정하면 빈 마스크가 나옵니다. 대신 `> 0` 또는 `>= 250`으로 임계값을 설정하세요.
</Note>

## 3단계: OpenAI 호환 endpoint 사용

이미 OpenAI SDK를 사용 중이라면, `/images/generations`는 OpenAI가 사용하는 것과 동일한 `background` 파라미터를 받습니다. 이를 `"transparent"`로 설정하고 `output_format`으로 `png` 또는 `webp`를 선택하세요.

```python theme={"system"}
import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.venice.ai/api/v1",
    api_key=VENICE_API_KEY,
)

result = client.images.generate(
    model="gpt-image-2-5-flare",
    prompt="A flat vector icon of a paper airplane, isolated, no background",
    output_format="webp",
    background="transparent",
    quality="low",
)

with open("icon.webp", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

`background`는 `transparent`, `opaque`, `auto`를 받습니다. `opaque`, `auto`, `null`은 모두 모델의 기본 동작을 유지하므로, 실제로 변화를 주는 값은 `transparent`뿐입니다. 이 endpoint에서 `output_format`의 기본값은 `png`이므로 생략할 수 있습니다.

## 4단계: 투명도를 유지하며 편집

`/image/edit`와 `/image/multi-edit` 모두 `transparent_background`를 받습니다. 원본 이미지가 투명할 필요는 없으며, 불투명한 사진을 전달하고 편집하면서 피사체를 분리하도록 모델에 요청할 수 있습니다.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=gpt-image-2-5-flare-edit" \
  -F "prompt=Make the apple green and remove the background" \
  -F "image=@apple.jpg" \
  -F "transparent_background=true" \
  -o apple-green.png
```

편집 endpoint에서 `output_format`을 생략하면 자동으로 추론됩니다. 일반적으로 1K 편집은 PNG, 2K/4K는 JPEG이지만, `transparent_background`가 `true`이면 모든 해상도에서 PNG로 추론됩니다. 따라서 WebP를 원할 때만 `output_format`을 명시적으로 보내면 됩니다.

multi-edit 형식도 동일하며, `image` 대신 `images[]`를 사용합니다. 제품 사진을 새로운 장면에 합성하고, 그 합성 결과를 자체 레이아웃에 배치할 수 있는 컷아웃으로 받아야 할 때 자연스럽게 활용할 수 있습니다.

## 가격

투명도에는 추가 요금이 없습니다. 모델의 일반 이미지당 가격을 지불하며, GPT Image 2.5의 경우 `resolution`과 `quality`에 따라 달라집니다. `gpt-image-2-5-flare`에서 `1K` `low` 생성은 `high` 또는 `4K`에 비용을 쓰기 전에 스티커나 아이콘을 반복 작업하는 가장 저렴한 방법입니다. 실시간 가격표는 [이미지 모델](/ko/models/image)을 참조하세요.

## 에러

검증은 모델이 호출되기 전에 실행됩니다. 두 메시지 모두 해결 방법을 알려줍니다.

| 요청 | 상태 | 본문 |
| - | - | - |
| `format` / `output_format`이 `jpeg`인 상태에서 `transparent_background: true` | `400` | `Transparent background requires png or webp output format.` |
| 플래그가 없는 모델에서 `transparent_background: true` | `400` | `Transparent background is not supported by model 'flux-2-pro'. Use a model with "supportsTransparentBackground": true in its constraints (see GET /api/v1/models).` |
| `/images/generations`에서 `output_format: "jpeg"`와 함께 `background: "transparent"` | `400` | `Transparent background requires png or webp output format.` |

`jpeg`와 함께 `transparent_background: false`를 사용하는 것은 문제없으며, 일반적인 불투명 JPEG를 반환합니다.

## 런타임에 지원 모델 확인하기

모델 ID는 바뀝니다. 위 목록을 하드코딩하는 대신 constraint 플래그로 `GET /models`를 필터링하세요. 이 키는 지원하는 모델에만 `true` 값으로 존재합니다.

```bash theme={"system"}
curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.constraints.supportsTransparentBackground == true) | .id'
```

편집 endpoint용으로는 `type=inpaint`를 사용하면 `-edit` 모델 ID가 반환됩니다.

## 언제 이것을 사용하고 언제 `/image/background-remove`를 사용하나요

| | `transparent_background` | `/image/background-remove` |
| - | - | - |
| 입력 | prompt(그리고 선택적으로 편집할 원본 이미지) | 기존의 불투명 이미지 |
| 알파 생성 방식 | 모델이 처음부터 투명도를 고려해 구성 | 분할 모델이 사후에 전경을 마스킹 |
| 그림자와 반사 | 모델이 피사체의 일부로 렌더링했으므로 부분 알파와 함께 유지 | 전경이 아니므로 배경과 함께 제거 |
| 모델 선택 | GPT Image 1.5 / 2.5만 해당 | 고정된 내부 모델, `model` 필드 없음 |
| 비용 | 모델의 일반 생성 또는 편집 가격 | 고정 배경 제거 가격 |

어차피 자산을 생성할 예정이라면 처음부터 투명도를 요청하고 두 번째 호출을 생략하세요. 불투명 이미지가 이미 있고 다시 생성하고 싶지 않을 때는 `/image/background-remove`를 사용하세요.

<Frame as="div" caption="1단계 요청으로 만든 투명 스티커 하나를 추가 처리 없이 세 가지 배경 위에 배치한 모습.">
  <img src="https://mintcdn.com/veniceai/W3Pe6eTTsq9YXpsg/images/guides/transparent-backgrounds/backgrounds.webp?fit=max&auto=format&n=W3Pe6eTTsq9YXpsg&q=85&s=4488165c3b98220102c945be301c64e1" alt="어두운 단색, 따뜻한 그라데이션, 체커보드 위에 각각 합성된 동일한 만화 로켓 스티커" width="1356" height="413" data-path="images/guides/transparent-backgrounds/backgrounds.webp" />
</Frame>

## 관련 문서

* [이미지 생성](/ko/guides/media/image-generation): 크기 조정, 품질 등급, 전체 `/image/generate` 파라미터 목록
* [이미지 편집](/ko/guides/media/image-editing): `/image/edit`, `/image/multi-edit`, `/image/background-remove`
* [이미지 모델](/ko/models/image): 현재 가격 및 constraints


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