---
title: Image 1.0
description: 프롬프트, 레퍼런스, 마스크 입력으로 Sume Image 1.0에서 이미지를 생성하고 편집하는 방법을 살펴보세요.
---

텍스트 프롬프트, 선택적 레퍼런스 이미지, 또는 마스크 기반 편집으로 스틸
이미지가 필요할 때 Image 1.0을 사용하세요. 프로바이더 모델은 Sume가 고르며,
호출자는 프로바이더 모델 id를 보내지 않습니다.

기본 실행 URL입니다.

```text
POST /v1/image-1.0/generate
```

model-run 별칭입니다(본문은 같습니다).

```text
POST /v1/models/sume/image-1.0/runs
```

공개 모델 id는 `sume/image-1.0`입니다.

## 언제 사용하나요

| 목표 | 방법 |
|---|---|
| 텍스트 → 이미지 | `prompt`만 사용합니다 |
| 편집 / 레퍼런스 | `prompt` + `image_urls`(공개 HTTPS URL 1~10개) |
| 마스크 편집 | `image_urls`와 함께 `mask_image_url`을 추가합니다 |

공개 HTTPS 이미지 URL만 사용하세요. localhost, 사설 네트워크, HTTPS가 아닌
URL은 제출 전에 거부됩니다.

## 요청 필드

| 필드 | 필수 | 설명 |
|---|---|---|
| `prompt` | 예 | 비어 있지 않은 문자열입니다. |
| `image_urls` | 아니요 | 레퍼런스·편집 이미지 URL 1~10개입니다. DEPRECATED된 `input_urls`보다 이 필드를 사용하세요. |
| `mask_image_url` | 아니요 | 편집 플로를 위한 마스크 이미지 URL입니다. |
| `aspect_ratio` | 아니요 | `1:1`, `9:16`, `16:9`, `4:3`, `3:4`와 gpt-image-2의 `5:4` / `9:8`입니다. `image_size`가 설정되면 무시됩니다. |
| `image_size` | 아니요 | 네임드 프리셋(`square`, `square_hd`, `portrait_16_9`, `landscape_16_9`, `landscape_4_3`, `portrait_4_3`) 또는 gpt-image-2 커스텀 `{ width, height }` / `WIDTHxHEIGHT`. 커스텀은 양변 16 배수, 긴 변 ≤3840, 비율 ≤3:1, 픽셀 655,360–8,294,400. `aspect_ratio`보다 우선합니다. |
| `quality` | 아니요 | `low`(기본), `medium`, `high`입니다. 최종본, 빽빽한 텍스트, 패키지 디자인에는 높이세요. |
| `num_images` | 아니요 | 1~4 정수입니다. DEPRECATED된 `n`보다 이 필드를 사용하세요. |
| `output_format` | 아니요 | `png`, `jpeg`, `jpg`, `webp`입니다. DEPRECATED된 `format`보다 이 필드를 사용하세요. |
| `metadata` | 아니요 | Job에 저장되는 호출자 메타데이터입니다. 프로바이더로 전달되지 않습니다. |
| `mode` | 아니요 | `async`(대부분의 클라이언트에서 생략 시 기본 동작), `sync`, `subscribe`, `webhook`입니다. |
| `webhook_url` | 아니요 | 웹훅 모드에서 종료 알림을 받을 공개 HTTPS 콜백입니다. |
| `wait_timeout_seconds` | 아니요 | 0~30입니다. `sync` / `subscribe`의 블로킹 대기 예산입니다. |

DEPRECATED된 별칭 `input_urls`, `n`, `format`도 여전히 받습니다. 위의 최신
이름을 사용하세요.

## 이미지 Job 만들기

<!-- api-call-example:image-generate -->

레퍼런스 · 편집 예제입니다.

```bash
curl -X POST https://api.sume.com/v1/image-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-edit-001" \
  -d '{
    "prompt": "Keep the product identical; swap the background to a soft daylight studio",
    "image_urls": ["https://example.com/product.png"],
    "quality": "medium",
    "aspect_ratio": "4:3"
  }'
```

같은 `Idempotency-Key`는 클라이언트 타임아웃 후 재시도할 때, 같은 오퍼레이션과
같은 페이로드에 대해서만 재사용하세요.
[Job과 결과](/workflows/jobs-and-results)에서 살펴보세요.

## 폴링하고 결과 가져오기

제출 응답에는 `status_url`, `result_url`, `events_url`, 그리고 선택적으로
`cancel_url`이 포함됩니다. Job이 종료 상태가 될 때까지 폴링한 다음 결과를
가져오세요.

```bash
curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## 산출물

완료된 Image 1.0 Job은 `result.artifacts[]` 아래에 Sume가 호스팅하는 미디어를
반환합니다.

```json
{
  "id": "job_...",
  "status": "completed",
  "result": {
    "artifacts": [
      {
        "id": "artifact_...",
        "type": "image",
        "url": "https://media.sume.com/artifacts/...",
        "content_type": "image/png"
      }
    ]
  }
}
```

반환된 Sume 미디어 URL을 사용하세요. 원본 프로바이더 URL은 공개 결과 계약에
포함되지 않습니다.

## 다음

- 프롬프트나 첫 프레임으로 움직임을 만들려면 [Video 1.0](/models/video)
- 모드, 취소, 이벤트는 [Job과 결과](/workflows/jobs-and-results)
- HTTPS URL 규칙은 [미디어 입력](/workflows/asset-library)
- 짧게 복사해 쓰는 플로는 [레시피](/api/cookbook)