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

# Seedream 5.0 Pro

> Dola Seedream 5.0 Pro 텍스트-이미지, 이미지-이미지, 다중 이미지 참조

## 소개

Seedream 5.0 Pro(모델 `dola-seedream-5-0-pro-260628`)는 텍스트-이미지, 단일 이미지 편집, 다중 이미지 참조/융합을 지원합니다. OpenAI 호환 이미지 생성 API로 동기 호출하며, 현재 요청당 출력은 **1장**입니다.

여러 참조 이미지는 **입력**이 여러 장임을 의미하며, 출력이 여러 장인 것은 아닙니다. 여러 결과가 필요하면 요청을 여러 번 보내세요.

전체 모델 비교는 [이미지 생성](/ko/api-reference/endpoint/image-generation)을 참고하세요.

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token, 예: `Bearer sk-xxxxxxxxxx`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

API Key는 플랫폼 API 키 페이지에서 생성하세요. 프론트엔드 코드, 공개 저장소, 클라이언트 패키지에 키를 넣지 마세요.

## 모델 정보

| 항목           | 설명                             |
| ------------ | ------------------------------ |
| 모델 ID        | `dola-seedream-5-0-pro-260628` |
| 텍스트-이미지      | 지원                             |
| 단일 이미지 편집    | 지원                             |
| 다중 이미지 참조/융합 | 지원                             |
| 요청당 출력 수     | 현재 1장                          |
| 프로토콜         | OpenAI 호환 이미지 생성               |
| 응답 방식        | 동기                             |

## 엔드포인트

```http theme={null}
POST https://api.gravitex.ai/v1/images/generations
```

## 요청 파라미터

| 파라미터              | 타입        | 필수  | 설명                                            |
| ----------------- | --------- | --- | --------------------------------------------- |
| `model`           | string    | 예   | 고정값 `dola-seedream-5-0-pro-260628`            |
| `prompt`          | string    | 예   | 이미지 생성 또는 편집 지시                               |
| `size`            | string    | 아니오 | 출력 크기: `1K`, `2K` 또는 `가로x세로` (예: `1024x1024`) |
| `images`          | string\[] | 아니오 | 참조 이미지 URL 배열; 없으면 텍스트-이미지                    |
| `n`               | integer   | 아니오 | 요청 생성 수; 현재 실제로는 1장만 반환 — `1` 권장              |
| `quality`         | string    | 아니오 | 이미지 품질, `standard` 사용                         |
| `output_format`   | string    | 아니오 | `jpeg` 또는 `png`, 기본값 `jpeg`                   |
| `response_format` | string    | 아니오 | `url` 또는 `b64_json`, 기본값 `url`                |
| `watermark`       | boolean   | 아니오 | 워터마크 추가 여부; 기본값 `false`                       |

### prompt

원하는 내용을 설명하는 필수 텍스트 지시입니다. 이미지-이미지에서는 참조 이미지를 어떻게 사용·수정할지도 함께 적습니다.

```json theme={null}
"prompt": "미래 도시 야경, 영화 포스터 스타일, 고세부, 청보라 네온"
```

### images

플랫폼이 접근 가능한 이미지 URL을 하나 이상 전달합니다:

```json theme={null}
"images": [
  "https://example.com/reference-1.png"
]
```

다중 참조 예시:

```json theme={null}
"images": [
  "https://example.com/subject.png",
  "https://example.com/style.jpeg"
]
```

<Note>
  * URL은 서버에서 접근 가능해야 하며, 로컬 브라우저에서만 유효해서는 안 됩니다.
  * 여러 이미지는 참조/융합/편집용이며, 결과는 여전히 1장입니다.
  * 현재 테스트·프로덕션 호출은 `images` 배열 필드를 사용합니다.
  * 형식, 크기, 개수, 접근성은 업스트림 모델 요구사항을 충족해야 합니다.
</Note>

### size

해상도 티어 또는 커스텀 픽셀 크기를 지원합니다:

```json theme={null}
"size": "1K"
```

```json theme={null}
"size": "2K"
```

```json theme={null}
"size": "1024x1024"
```

일반적인 크기:

| 요청 크기       | 일반적인 실제 출력  |
| ----------- | ----------- |
| `1024x1024` | `1024x1024` |
| `2048x2048` | `2048x2048` |

## 호출 예시

<Tabs>
  <Tab title="텍스트-이미지">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "미래 도시 야경, 영화 포스터 스타일",
        "size": "1024x1024",
        "n": 1
      }'
    ```
  </Tab>

  <Tab title="이미지-이미지">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "참조 이미지를 바탕으로 검은 새끼 양 생성",
        "size": "1024x1024",
        "n": 1,
        "images": [
          "https://example.com/reference.png"
        ]
      }'
    ```
  </Tab>

  <Tab title="다중 이미지 융합">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "두 참조 이미지를 융합해 흑백 새끼 양 생성",
        "size": "1024x1024",
        "n": 1,
        "images": [
          "https://example.com/reference-1.png",
          "https://example.com/reference-2.jpeg"
        ]
      }'
    ```
  </Tab>

  <Tab title="PNG 출력">
    ```bash theme={null}
    curl --location 'https://api.gravitex.ai/v1/images/generations' \
      --header 'Authorization: Bearer sk-xxxxxxxxxx' \
      --header 'Content-Type: application/json' \
      --data '{
        "model": "dola-seedream-5-0-pro-260628",
        "prompt": "미니멀 제품 홍보 이미지 생성",
        "size": "2K",
        "output_format": "png",
        "watermark": false
      }'
    ```
  </Tab>
</Tabs>

## 성공 응답

플랫폼은 OpenAI 호환 이미지 생성 결과를 반환합니다:

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "created": 1784868948,
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "1024x1024",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}
```

### 응답 필드

| 필드                       | 타입      | 설명                         |
| ------------------------ | ------- | -------------------------- |
| `model`                  | string  | 실제 사용된 모델 이름               |
| `created`                | integer | 생성 시간(Unix 타임스탬프)          |
| `data`                   | array   | 출력 이미지 목록, 보통 1개           |
| `data[].url`             | string  | 이미지 주소 — 즉시 다운로드하세요        |
| `data[].b64_json`        | string  | `b64_json` 사용 시 Base64 이미지 |
| `data[].size`            | string  | 실제 출력 픽셀 크기                |
| `data[].output_format`   | string  | 실제 출력 형식                   |
| `usage.input_images`     | integer | 입력 참조 이미지 수                |
| `usage.generated_images` | integer | 생성된 이미지 수                  |
| `usage.output_tokens`    | integer | 출력 토큰 사용량                  |
| `usage.total_tokens`     | integer | 총 토큰 사용량                   |

<Warning>
  `data[].url`은 보통 임시 주소입니다. 응답을 받은 후 즉시 다운로드해 자체 스토리지에 보관하세요.
</Warning>

## 다중 이미지 안내

이 모델은 현재 요청당 1장만 반환합니다. 아래 요청은 참조 이미지 2장을 넣을 수 있지만 결과는 여전히 1장입니다:

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "두 참조 이미지를 융합해 새 이미지 한 장 생성",
  "images": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ],
  "n": 1
}
```

독립 결과 3장이 필요하면 `n: 3`에 의존하지 말고 요청을 3번 보내세요:

```text theme={null}
요청 1: n=1
요청 2: n=1
요청 3: n=1
```

## 오류 처리

요청 실패 시 보통 JSON 오류 객체를 반환합니다:

```json theme={null}
{
  "error": {
    "message": "오류 설명",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}
```

자주 발생하는 문제:

| 문제           | 처리 제안                           |
| ------------ | ------------------------------- |
| API Key 무효   | `Authorization: Bearer ...` 확인  |
| `prompt` 누락  | 비어 있지 않은 `prompt` 필수            |
| 참조 이미지 읽기 실패 | URL 공개 접근 가능 여부·만료 여부 확인        |
| 지원하지 않는 크기   | `1K`, `2K` 또는 모델 제한 내 커스텀 크기 사용 |
| 미지원 파라미터     | 미지원 필드 제거 후 재시도                 |
| 한 번에 여러 장 생성 | `n=1` 요청을 여러 번 전송               |
| 반환 URL 만료    | 응답 직후 즉시 다운로드·영구 저장             |