> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Midjourney API 개요

>  - Midjourney 텍스트→이미지(Imagine) / 참조 이미지 / 2차 작업 / 이미지→동영상 엔드포인트 개요
- 비동기 작업 모드: 제출 후 task_id 반환, 결과를 폴링
- 새 라우트는 model=midjourney를 자동 주입하며 네이티브 MJ 인자, 구조화 body 필드, metadata를 지원 

<Note>
  **Base URL:** `https://api.apimart.ai`

  **인증:** `Authorization: Bearer <token>`

  새 `/v1/midjourney/...` 라우트는 `model=midjourney`를 자동 주입하므로 요청 본문에 `model`을 전달할 필요가 없습니다.
</Note>

## 빠른 시작

```bash theme={null}
# 1. Imagine 작업 제출
curl -X POST https://api.apimart.ai/v1/midjourney/generations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cute cat, watercolor style --ar 16:9"}'

# 2. 통합 작업 API를 status=completed까지 폴링
curl https://api.apimart.ai/v1/tasks/task_01JWXXXX \
  -H "Authorization: Bearer <token>"

# 3. 첫 번째 이미지 업스케일
curl -X POST https://api.apimart.ai/v1/midjourney/generations/upscale \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task_01JWXXXX", "index": 1}'
```

## API 개요

각 기능의 전체 필드, 예시, 주의사항은 해당 하위 페이지를 참고하세요.

| 기능                 | 경로                                                               | 문서                                 |
| ------------------ | ---------------------------------------------------------------- | ---------------------------------- |
| 텍스트→이미지(기본 엔드포인트)  | `POST /v1/midjourney/generations`                                | [Imagine](./imagine)               |
| 텍스트→이미지(명시적 엔드포인트) | `POST /v1/midjourney/generations/imagine`                        | [Imagine](./imagine)               |
| 다중 이미지 블렌드         | `POST /v1/midjourney/generations/blend`                          | [Blend](./blend)                   |
| 이미지→텍스트            | `POST /v1/midjourney/generations/describe`                       | [Describe](./describe)             |
| 이미지 편집             | `POST /v1/midjourney/generations/edits`                          | [Edits](./edits)                   |
| 업스케일               | `POST /v1/midjourney/generations/upscale`                        | [Upscale](./upscale)               |
| 변형                 | `POST /v1/midjourney/generations/variation`                      | [Variation](./variation)           |
| 강한 변형              | `POST /v1/midjourney/generations/high-variation`                 | [High Variation](./high-variation) |
| 약한 변형              | `POST /v1/midjourney/generations/low-variation`                  | [Low Variation](./low-variation)   |
| 리롤                 | `POST /v1/midjourney/generations/reroll`                         | [Reroll](./reroll)                 |
| 줌 아웃               | `POST /v1/midjourney/generations/zoom`                           | [Zoom](./zoom)                     |
| 팬                  | `POST /v1/midjourney/generations/pan`                            | [Pan](./pan)                       |
| 인페인트               | `POST /v1/midjourney/generations/inpaint`                        | [Inpaint](./inpaint)               |
| Modal 추가 파라미터      | `POST /v1/midjourney/generations/modal`                          | [Modal](./modal)                   |
| 이미지→동영상            | `POST /v1/midjourney/generations/video`                          | [Video](./video)                   |
| 리셰이프(강 / 약)        | `POST /v1/midjourney/generations/remix-strong` · `/remix-subtle` | [Remix](./remix)                   |
| 작업 조회              | `GET /v1/tasks/{task_id}` · `/v1/midjourney/{task_id}`           | [작업 조회](./query)                   |

참고: [모범 사례](./best-practices)(폴링 / 재시도 / 문제 해결) · [전체 워크플로 예시](./workflow)(엔드투엔드 curl + 클라이언트 래퍼)

## 전체 흐름

```mermaid theme={null}
flowchart TB
  A["① POST /generations<br/>Imagine 제출"] --> B["② GET /v1/tasks/{task_id}<br/>completed까지 폴링"]
  B --> C["③ buttons가 필요하면<br/>GET /v1/midjourney/{task_id}"]
  C --> D1["/upscale"]
  C --> D2["/variation"]
  C --> D3["/reroll"]
  C --> D4["/zoom"]
  C --> D5["/inpaint<br/>(MODAL로 진입)"]
  D5 --> M["/modal<br/>마스크 + prompt 제출"]
```

## 오류 처리

### 오류 응답 형식

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "prompt is required"
  }
}
```

### 일반 오류

| HTTP | type                    | 설명                       |
| ---- | ----------------------- | ------------------------ |
| 400  | `invalid_request_error` | 파라미터 오류 (필수 누락, 형식 오류 등) |
| 401  | `authentication_error`  | API Key 무효               |
| 402  | `payment_required`      | 잔액 부족                    |
| 404  | `not_found`             | 작업이 존재하지 않음              |
| 429  | `rate_limit_error`      | 요청 빈도 초과                 |
| 500  | `internal_error`        | 서버 내부 오류                 |

### 작업 실패

작업 실패 시 `fail_reason`이 원인을 반환합니다. 일반적인 값:

* `Banned prompt detected` — 금지어 포함
* `Task timeout` — 작업 시간 초과 (30분 초과). 자동 전액 환불 완료
* `No available upstream` — 서비스 일시적으로 사용 불가, 잠시 후 재시도

## 과금

MJ 새 라우트의 통합 모델명은 `midjourney`입니다. action, version, speed로 과금 key를 생성합니다. 일반적인 매칭 순서는 다음과 같습니다.

```text theme={null}
midjourney@<action>-<version>-<speed>
-> midjourney@<action>-<version>
-> midjourney@<action>-<speed>
-> midjourney@<action>
-> midjourney
```

| 작업             | 과금 키                                          | 설명                            |
| -------------- | --------------------------------------------- | ----------------------------- |
| Imagine        | `midjourney@imagine[-version][-speed]`        | 텍스트→이미지 / 참조 이미지 생성           |
| Blend          | `midjourney@blend[-speed]`                    | 다중 이미지 블렌드                    |
| Describe       | `midjourney@describe[-speed]`                 | 이미지→텍스트                       |
| Edits          | `midjourney@edits[-speed]`                    | 이미지 편집                        |
| Upscale        | `midjourney@upscale[-version][-speed]`        | 업스케일                          |
| Variation      | `midjourney@variation[-version][-speed]`      | 변형                            |
| High Variation | `midjourney@high_variation[-version][-speed]` | 강한 변형                         |
| Low Variation  | `midjourney@low_variation[-version][-speed]`  | 약한 변형                         |
| Reroll         | `midjourney@reroll[-version][-speed]`         | 다시 생성                         |
| Zoom           | `midjourney@zoom[-version][-speed]`           | 줌 아웃 / 확장                     |
| Pan            | `midjourney@pan[-version][-speed]`            | 팬 확장                          |
| Inpaint        | `midjourney@inpaint[-version][-speed]`        | 인페인트 진입                       |
| Modal          | `midjourney@modal[-speed]`                    | 인페인트 추가 파라미터                  |
| Video          | `midjourney@video` / `midjourney@video-720p`  | 이미지→동영상, 실제 청구 × `batch_size` |
| Remix Strong   | `midjourney@remix_strong[-speed]`             | 강 리셰이프(v8.1 / v8.2 전용)        |
| Remix Subtle   | `midjourney@remix_subtle[-speed]`             | 약 리셰이프(v8.1 / v8.2 전용)        |

설명:

* `speed=relax` 또는 `speed` 미전달 시 speed 접미사가 추가되지 않습니다. `fast` / `turbo`는 해당 접미사를 추가합니다.
* 주 버전은 `v8.2`, `v8.1`, `v7`, `v6.1`, `v5.2`, `v5.1`로 정규화됩니다.
* `niji=true + version=7/6`은 `niji7` / `niji6`으로 정규화됩니다.

> 자세한 가격은 콘솔의 모델 가격 페이지 참조. 실패 시 자동 전액 환불.