Midjourney 이미지 모델(Beta), 기본 V8.2. 프롬프트와 파라미터는 midjourney.com과 같은 표기이며, 한 번에 PNG 원본 4장 한 세트를 1회 요금으로 만듭니다. 업스케일, 변형, 리믹스, 줌, 팬도 같은 API입니다.
플레이그라운드에서 사용해 보기 →빠른 시작
다른 이미지 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
콘솔에서 API 키를 만들면 시작할 수 있습니다.
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| 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}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 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로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 오류 코드에 있습니다.
제출할 때 돌아오는 오류
| 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로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. 웹훅 문서 →
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"}'