Midjourney V8.2 API: 이미지 작업 제출과 결과 폴링

Midjourney V8.2 API를 연동하려면 명확한 버전, 유효한 이미지 요청, 완료된 작업을 가져오는 방법이 필요합니다. SeedRouter에서는 /v1/images/generations에 제출하고 반환된 작업 ID를 보관한 뒤 /v1/tasks/{id}를 폴링합니다. 제출 성공은 작업이 접수되었다는 뜻이며, 이미지는 완료 결과로 전달됩니다.

이 가이드는 SeedRouter 요청 계약을 따릅니다. 2026년 10월 18일 유료 검증에서 V8.2 고속 요청이 완료되어 1024 × 1024 이미지 4장이 전달되었습니다. 아래 인물 사진은 그중 하나입니다. 모델 페이지에는 Playground와 실시간 요금이 있으며, API 참조 문서는 지원되는 입력과 아직 검증이 필요한 조합을 구분합니다. ^[1]

명확한 Midjourney V8.2 API 요청으로 시작하기

전체 모델 ID인 midjourney-v8.2를 사용합니다. SeedRouter는 모델을 명시해야 합니다. midjourney로 줄이거나 다른 인터페이스의 계정 설정에서 추정하지 마세요. 제출한 요청과 함께 모델도 기록합니다. ^[1]

서버 측 API 키와 결과를 확인하기 쉬운 짧은 프롬프트를 준비합니다. 첫 요청에서는 기본 경로를 테스트할 수 있도록 참조나 상위 이미지 작업을 제외합니다. 아래 요청은 이 글에 나온 인물 사진 세트를 생성했습니다. 고속 모드를 선택하고 추가 콘텐츠 검사를 켭니다.

{
  "model": "midjourney-v8.2",
  "prompt": "Cinematic portrait of a young woman with freckles and wind-swept auburn hair, wearing a cream cable-knit sweater, laughing on a coastal cliff at golden hour, warm rim light, shallow depth of field, 85mm film photograph",
  "speed": "fast",
  "nsfw_check": true
}

최소 요청에는 model과 prompt만 필요합니다. 속도를 생략하면 기본값은 고속입니다. size를 추가한다면 WIDTHxHEIGHT 픽셀 지시가 아니라 "16:9"와 같은 화면비를 사용합니다. 일반 이미지 클라이언트 프리셋이 보내는 1024x1024, quality: "high", 임의의 n은 이 모델의 계약에 맞지 않습니다. 다른 모델의 설정을 그대로 재사용하지 말고 Midjourney 필드 표에 맞춰 본문을 조정합니다.

한 번 제출하고 저장한 작업 ID를 폴링하기

내려받을 수 있는 Python 예제는 표준 라이브러리를 사용하며, 키를 환경 변수에 보관하고 접수된 작업 ID를 로컬 파일에 기록합니다. 제출 명령과 폴링 명령이 분리되어 있습니다. 덕분에 이미지 작업을 새로 만들지 않고 읽기를 재개할 수 있습니다.

export SEEDROUTER_API_KEY='your-server-side-key'
python3 midjourney-v8-2.py submit request.json --state mj-task.json
python3 midjourney-v8-2.py poll --state mj-task.json

위 JSON 요청을 request.json으로 저장합니다. 로컬 환경에서 예제 키를 자신의 비밀 키로 바꾸세요. 브라우저 번들에 넣거나 저장소에 커밋하지 않습니다. 로컬 배포를 테스트하려면 예제의 SEEDROUTER_BASE_URL을 해당 배포의 /v1 기본 URL로 설정합니다.

예제는 제출 시 기존 상태 파일을 덮어쓰지 않습니다. 연결 실패 후 POST를 자동으로 반복하지도 않습니다. 응답이 유실되면 애플리케이션은 작업 접수 여부를 모를 수 있습니다. 재제출을 결정하기 전에 작업 기록을 확인합니다.

폴링은 이미 존재하는 작업을 읽는 것이므로 다릅니다. 예제는 작업이 완료되거나 실패하면 멈추며, 계속 처리 중이면 대기 한도에 도달했음을 알립니다. 대기 한도는 클라이언트 측 관찰일 뿐, 작업을 다시 생성해야 한다는 증거가 아닙니다.

작업별 결과 구조 읽기

완료된 이미지 작업은 output.data에 URL을 반환합니다. 항상 항목 4개가 있다고 가정하지 말고 배열을 순회합니다. 이미지 생성, 이미지 1장 선택, 이미지 설명, 편집 입력 단계는 서로 다른 출력 유형을 반환할 수 있습니다.

작업을 읽는 HTTP 요청이 성공했더라도 실패한 작업은 애플리케이션에서 실패로 처리합니다. HTTP 성공은 상태 조회가 처리되었다는 뜻이지, 요청한 이미지가 생성되었다는 뜻이 아닙니다.

output.grid가 true이면 URL 하나에 그리드가 포함됩니다. 이 파일에서 개별 URL 4개를 임의로 만들어서는 안 됩니다. 후속 선택에서는 그리드의 1부터 시작하는 이미지 위치를 사용합니다. URL 수와 선택 가능한 후보 수는 다릅니다.

예제는 완료된 출력을 JSON으로 출력합니다. 애플리케이션은 반환된 이미지에 저장, 썸네일, 선택 제어 기능을 추가할 수 있습니다. 후속 작업이 올바른 상위 작업을 참조하도록 작업 ID를 결과와 함께 보관합니다.

충돌을 숨기지 않고 네이티브 매개변수 변환하기

이 연동은 구조화된 필드와 지원되는 네이티브 프롬프트 플래그를 받습니다. 우선순위는 구조화된 필드, extra, prompt 안의 플래그 순서입니다. 명시적인 0과 false 값은 유지됩니다.

예를 들어 --stylize 700이 포함된 프롬프트에 "stylize": 0을 함께 지정하면 명시적인 0이 사용됩니다. UI가 별도 제어 값을 전송할 때 유용하지만, 프롬프트와 JSON을 서로 다른 곳에서 조립하는 애플리케이션에는 예상 밖일 수 있습니다. 각 설정의 출처를 하나로 두는 것이 좋습니다.

SeedRouter V8.2 요청에서 quality는 호환되는 조합에 한해 0.25, 0.5, 1 또는 2를 받습니다. 품질과 hd는 독립적인 입력이므로 품질을 설정해도 HD가 선택되지는 않습니다. 둘을 함께 넣거나 다른 참조 제어 기능을 추가하기 전에 현재 조합 제한을 확인합니다. 문서화된 입력이라고 해서 모든 버전에서의 효과가 입증된 것은 아닙니다. Raw도 둘과 별개입니다. Raw 가이드에서 차이를 설명합니다. ^[1]

이 연동은 알 수 없는 JSON 필드는 버리지만, 알 수 없는 네이티브 플래그는 거부합니다. 요청이 접수되었다는 사실을 무관한 추가 JSON 필드가 출력에 영향을 주었다는 증거로 삼지 마세요. 문서화된 필드명을 확인하고 실제 제출 본문을 테스트 기록에 보관합니다.

상위 이미지 작업을 원래 작업에 연결하기

후속 작업에는 SeedRouter의 parent_task_id를 사용합니다. 종속 작업은 원래 실행 맥락에 연결된 상태를 유지합니다. 그 맥락을 사용할 수 없으면 다른 곳에서 상위 작업을 새로 만들지 않고 실패합니다. 상위 작업은 같은 계정 소유여야 하며, 같은 모델을 사용하고 요청한 작업에 여전히 사용할 수 있어야 합니다. 공개 이미지 인덱스는 1부터 시작합니다.

이미지 선택과 창의적 업스케일은 다른 작업입니다. select 결과를 해상도 향상이라고 설명해서는 안 됩니다. 변형, 리믹스, 공식 V8.2 Edit Model도 서로 다른 요구사항을 가진 별개 기능입니다.

현재 연동은 새로운 Edit Model을 검증된 API 작업으로 제공하지 않습니다. 기존 인페인트 요청으로 대신하고 같은 동작을 제공한다고 가정하지 마세요. 편집 가이드는 사용할 수 있는 대안과 검증된 V6.1 마스크 편집 흐름을 설명하고, API 참조 문서는 구현된 작업 제한을 기록합니다.

썸네일 수가 아니라 작업 단위로 예상하기

이 연동의 요금 계약에서는 완료된 생성 1회가 작업 1건입니다. 그리드에서 기존 이미지를 선택해도 새로운 유료 생성이 만들어지지 않습니다. 편집 입력 단계에 들어가도 생성 요금이 한 번 더 붙지 않습니다. 최종 modal 작업이 과금 단계입니다. 이미지 4장 생성이 자동으로 별도 과금 작업 4건이 되는 것은 아닙니다. 10월 18일 V8.2 초안 검증에서는 작업 1건에 이미지 24장이 반환되었습니다. 따라서 반환 이미지 수는 안전한 요금 공식이 아닙니다.

선택한 버전, 작업, 속도, 모드의 현재 요금을 사용합니다. 상위 이미지 작업은 설정을 상속할 수 있으므로, 추정한 기본값이 아니라 실제 유효 요청으로 요금을 구해야 합니다. 모델 페이지는 이 튜토리얼에 영구적인 달러 금액을 넣지 않고 설정된 요금을 읽습니다.

인수 테스트에서는 요청, 작업 ID, 최종 상태, 출력 수, 계정의 실제 과금을 기록합니다. 컴파일 성공이나 모의 HTTP 테스트로는 이러한 실행 시 사실을 확인할 수 없습니다. SeedRouter는 실패한 요청에 과금하지 않습니다.

자주 묻는 질문

같은 API 키를 프런트엔드 JavaScript에서 사용해도 되나요?

서버에 보관합니다. 브라우저는 인증된 애플리케이션 엔드포인트를 호출하고, 그 엔드포인트가 서버 측 키로 요청을 제출하게 합니다.

작업 ID가 있으면 이미지가 준비된 건가요?

아닙니다. 작업이 완료 또는 실패를 보고할 때까지 읽은 뒤, 해당 결과를 처리합니다. 폴링을 시작하기 전에 ID를 저장합니다.

타임아웃이면 새로 생성해야 하나요?

자동으로 새로 생성하지 않습니다. 알고 있는 작업 ID를 보관하고 기존 작업을 확인합니다. 연결이나 클라이언트 대기 타임아웃은 원래 제출이 거부되었다는 뜻이 아닙니다.

상위 이미지 작업의 버전을 바꿀 수 있나요?

이 연동은 상위 작업과 같은 모델을 요구합니다. 다른 버전을 평가하려면 별도의 생성을 시작합니다.

Midjourney V8.2 API 연동은 명시적인 요청 하나와 저장된 작업 ID로 시작합니다. 참조나 연속 이미지 작업을 추가하기 전에 전달된 출력과 과금을 확인합니다.

출처

계약과 실행 증거는 2026년 10월 18일에 확인했습니다. 여기의 이미지는 유료 연동 검증에서 나온 출력이며 일반적인 모델 벤치마크가 아닙니다.

[1] SeedRouter Midjourney API 참조 문서

[2] 버전별 모델 설정과 현재 요금