# Midjourney — /images/generations

Midjourney 이미지 모델(Beta), 기본 V8.2. 프롬프트와 파라미터는 midjourney.com과 같은 표기이며, 한 번에 PNG 원본 4장 한 세트를 1회 요금으로 만듭니다. 업스케일, 변형, 리믹스, 줌, 팬도 같은 API입니다.

**엔드포인트:** `POST https://kovapi.com/v1/images/generations`

## 빠른 시작

다른 이미지 API와 같은 비동기 작업입니다. 제출해 작업 id를 받고 폴링으로 결과를 가져옵니다. 아래 3단계는 텍스트-투-이미지, 결과 확인, 2번째 이미지 업스케일입니다.

**1단계: 텍스트-투-이미지 제출(파라미터는 프롬프트 끝)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "speed": "fast"}'
```

응답(HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1795248736,
  "model": "midjourney"
}
```

**2단계 · `status`가 `succeeded` 또는 `failed`가 될 때까지 2~3초마다 조회**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

data에 PNG 원본 4장(1~4 순서), actions에 다음에 할 수 있는 작업이 들어 있습니다.

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1795248736,
  "model": "midjourney",
  "data": [
    {"url": "https://img.kovapi.com/i/5b2c0e8a1f3d4c6b9a7e2d1c0b3a4f5e.png"},
    {"url": "https://img.kovapi.com/i/0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f.png"},
    {"url": "https://img.kovapi.com/i/7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d.png"},
    {"url": "https://img.kovapi.com/i/3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b.png"}
  ],
  "usage": {"images": 4, "model": "midjourney", "speed": "fast", "action": "imagine"},
  "actions": ["upscale", "vary", "remix", "reroll", "zoom", "pan"]
}
```

**3단계: 이어서 작업 — 2번째 이미지 업스케일(같은 API에 task_id, action, index)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "task_id": "img_7f3c9a1e2b4d6f8a0c1e3b5d", "action": "upscale", "index": 2, "mode": "subtle"}'
```

**전체 예제(Python: 제출 → 대기 → 로컬에 저장)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def run(body):
    job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json=body).json()
    if "error" in job:
        raise SystemExit(job["error"]["message"])
    while job["status"] not in ("succeeded", "failed"):
        time.sleep(5)
        job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
    if job["status"] == "failed":
        raise SystemExit(job["error"]["message"])
    return job

# 텍스트-투-이미지 후 2번째 이미지 업스케일
grid = run({"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2"})
print([d["url"] for d in grid["data"]], grid["actions"])
big = run({"model": "midjourney", "task_id": grid["id"], "action": "upscale", "index": 2})
with open("midjourney-2.png", "wb") as f:
    f.write(requests.get(big["data"][0]["url"]).content)
```

## 인증
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| model | string | 예 | 모델 ID. 여기서는 midjourney입니다. |
| prompt | string | 아니오 | 프롬프트. Midjourney 파라미터는 공식처럼 끝에 씁니다(--ar, --v, --niji, --s, --c, --w, --seed, --no, --sref, --oref, --cref, --iw, --raw, --tile, --hd, --draft). 텍스트-투-이미지, remix, edit에는 필수이며 최대 6000자입니다. --repeat와 {a, b}는 지원하지 않습니다. |
| speed | string | 아니오 | `relax`(기본값, $0.045), `fast`($0.055), `turbo`($0.10). 프롬프트에 --relax / --fast / --turbo를 써도 되며 이 필드가 우선합니다. |
| images | array | 아니오 | 이미지 프롬프트. 최대 5장, 이미지 URL·data: URI·base64. Midjourney처럼 프롬프트 앞에 놓이며 --iw로 가중치를 줄 수 있습니다. action이 blend이면 섞을 이미지 2~5장. |
| size | string | 아니오 | 비율(예: `3:2`) 또는 픽셀 크기. 프롬프트에 --ar가 없으면 --ar로 바꿉니다(프롬프트의 --ar가 우선). edit에서 둘 다 없으면 원본 이미지 비율을 따릅니다. |
| task_id | string | 아니오 | 이어서 작업할 작업 id(img_로 시작, 완료, 7일 이내). |
| action | string | 아니오 | `upscale`(2배, mode subtle / creative), `vary`(strength strong / subtle), `remix`(새 프롬프트), `reroll`, `zoom`(1~2배 줌아웃), `pan`(direction), `inpaint`(mask). task_id 없이 쓰는 `blend`(2~5장), `edit`(이미지 1장 + 수정 지시). |
| index | integer | 아니오 | 몇 번째 이미지인지(1~4). 업스케일한 단일 이미지는 생략 가능. |
| n | integer | 아니오 | 1만 가능: 한 번이 4장 한 세트이며 한 번으로 과금됩니다. |
| callback_url | string | 아니오 | 작업이 끝나면 결과를 보낼 주소. 아래 웹훅 부분을 보세요. |

## 이어서 하는 작업(task_id + action)

완료된 작업(7일 이내)을 이어서 합니다. 공식 앱의 버튼과 하나씩 대응하며, 결과는 새 작업으로 선택한 속도에 따라 과금됩니다.

| action | 보낼 필드 | 하는 일 |
| --- | --- | --- |
| upscale | index, mode | 2배 업스케일: mode는 `subtle`(기본값, 디테일 유지) 또는 `creative`(디테일 추가). 1장을 돌려줍니다. |
| vary | index, strength | index번째 이미지를 바탕으로 변형 4장: strength는 `strong`(기본값) 또는 `subtle`. |
| remix | index, prompt, strength | 구도를 유지하고 새 prompt에 맞춰 다시 만들기, 4장. |
| reroll | — | 같은 프롬프트로 한 세트 전체 다시 생성, 4장. |
| zoom | index, zoom | 화면을 바깥으로 넓히기: zoom 1~2(기본값 2), 4장. |
| pan | index, direction | left / right / up / down으로 넓히기, 4장. |
| inpaint | index, mask, prompt | mask의 흰색(또는 투명) 영역만 다시 그립니다. mask는 원본과 같은 비율이면 원본 크기로 자동 조정됩니다. 결과의 actions에 inpaint가 있을 때만 쓸 수 있습니다. |
| blend | images(2~5장) | task_id 없이: 이미지 2~5장을 섞어 4장 한 세트로. 비율은 prompt에 씁니다(예: `--ar 3:2`). |
| edit | image, prompt | task_id 없이: 이미지 1장과 수정 지시 한 문장(V8.2 / 8.1), 4장. 원본 이미지 비율 그대로 나오며, 바꾸려면 prompt에 --ar를 쓰거나 size를 지정하세요. |

## 가격

작업당 과금이며 한 번은 4장 한 세트(업스케일은 1장)입니다. 이어서 하는 작업은 선택한 속도의 1회 요금과 같습니다. --hd(V8 계열)는 2배, V7의 --draft는 반값(크레딧 단위로 내림)이며, HD 이미지의 변형이나 다시 생성도 2배입니다. 제출할 때 예치하고 실패하면 전액 돌려드립니다.

| 속도 | 장당 크레딧 | 장당 가격(USD) |
| --- | --- | --- |
| Relax(기본값) | 9 | $0.045 |
| Fast | 11 | $0.055 |
| Turbo | 20 | $0.10 |

## 크기, 버전과 제한

- Midjourney가 생성한 PNG 원본(Midjourney가 직접 기록한 콘텐츠 메타데이터 포함)을 자르거나 크기를 바꾸지 않고 전달합니다. 크기는 비율을 따릅니다: 1:1은 1024×1024, 3:2는 1344×896, 16:9는 1456×816. --hd와 업스케일은 2배입니다.

- 버전: 쓰지 않으면 V8.2. --v 8.1 / 8 / 7 / 6.1 / 6, --niji 7 / 6도 쓸 수 있습니다. --hd는 V8 계열만, --draft는 V7과 V8 계열만(V8 초안은 정상 요금이며 24장이 올 수 있습니다).

- --repeat / --r와 {a, b}(한 번에 여러 작업이 되는 표기)는 지원하지 않습니다. n은 1만 가능합니다.

- 이미지 프롬프트는 최대 5장이며 Midjourney처럼 프롬프트 앞에 놓입니다(--iw로 가중치). 스타일 참조는 --sref <이미지 URL>, V7 옴니 참조는 --oref <이미지 URL>.

- 결과와 업로드한 이미지는 7일간 보관되며, 그보다 오래된 작업은 이어서 할 수 없습니다.

- Describe(이미지에서 프롬프트)와 Midjourney 영상은 아직 제공하지 않습니다.

## 작업 상태와 응답 필드

`GET /v1/images/jobs/{id}`는 아래 상태를 돌려줍니다. 각 필드의 설명은 [비동기 작업](https://docs.kovapi.com/ko/guide/async-jobs#fields)에 있습니다. 2~3초마다 조회하거나 웹훅을 쓰세요.

| 상태 | 의미 |
| --- | --- |
| queued | 대기 중. `queue_position`(앞에 있는 작업 수)과 `eta_seconds`(예상 대기 시간)가 함께 옵니다. |
| processing | 생성 중. |
| succeeded | 완료. 결과는 `data[0].url`, 과금 내역은 `usage`에 있습니다. |
| failed | 실패. 사유는 `error`에 있고, 예약된 크레딧은 전액 환불됩니다. |

한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 이미지 링크는 7일 동안 보관됩니다.

## 생성 시간

실측(11-21): Relax와 Fast로 4장 약 1.5~2분, Turbo 약 1.5분. 업스케일 약 2분, 줌·팬 약 1.3분, 이미지 프롬프트나 블렌드는 약 4분. 혼잡할 때는 더 걸릴 수 있습니다.

## 오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 [오류 코드](https://docs.kovapi.com/ko/guide/errors)에 있습니다.

### 제출할 때 돌아오는 오류

| HTTP | code | 원인 | 조치 |
| --- | --- | --- | --- |
| 400 | invalid_request | 참조 이미지를 읽을 수 없거나(링크가 열리지 않음, 이미지가 아님, 16MB 초과 등. `message`에 몇 번째인지와 이유가 적혀 있습니다), `/v1/images/edits`에 참조 이미지가 없거나, 요청 본문이 JSON 객체가 아니거나, `n`이 정수가 아닙니다. | `message`에 적힌 대로 고친 뒤 다시 제출하세요. |
| 400 | unsupported_action | 참조 이미지를 읽을 수 없거나(링크가 열리지 않음, 이미지가 아님, 16MB 초과 등. `message`에 몇 번째인지와 이유가 적혀 있습니다), `/v1/images/edits`에 참조 이미지가 없거나, 요청 본문이 JSON 객체가 아니거나, `n`이 정수가 아닙니다. | `message`에 적힌 대로 고친 뒤 다시 제출하세요. |
| 404 | task_not_found | 참조 이미지를 읽을 수 없거나(링크가 열리지 않음, 이미지가 아님, 16MB 초과 등. `message`에 몇 번째인지와 이유가 적혀 있습니다), `/v1/images/edits`에 참조 이미지가 없거나, 요청 본문이 JSON 객체가 아니거나, `n`이 정수가 아닙니다. | `message`에 적힌 대로 고친 뒤 다시 제출하세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 503 | service_unavailable | 참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. `/v1/responses`는 잠시 요청을 처리할 수 없을 때도 `Retry-After`와 함께 503을 돌려줍니다. | 잠시 후 다시 시도하세요. |

### 작업 실패(`status`가 `failed`)

| code | 언제 나오나요 | 조치 |
| --- | --- | --- |
| moderation_blocked | 이미지: 모델 제공사의 안전 시스템이 프롬프트나 참조 이미지를 거부했습니다(코드가 `content_policy_violation`일 수도 있습니다). | 프롬프트를 고쳐 쓰거나 참조 이미지를 바꾸세요. 그대로 다시 제출하면 대개 다시 거부됩니다. |
| upstream_error | 그 밖의 실패: 자동 재시도 후에도 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 `message`에 있습니다. | 다시 제출하면 대개 성공합니다. |

## 조회 대신 웹훅으로 받기

제출할 때 `callback_url`을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. [웹훅 문서 →](https://docs.kovapi.com/ko/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "callback_url": "https://your-domain.com/webhook"}'
```
