# Midjourney Integration Guide

## Mode Endpoints

The two operating modes use different pricing:

- **fast mode**: {{BASE_URL}}/mj-fast
- **relax mode**: {{BASE_URL}}/mj-relax

Mode and image-return proxy behavior can also be controlled through token-side settings.

## API Categories

### Category 1: Create a New Task

- Imagine task (text-to-image / image-guided image): /mj/submit/imagine
- Blend task (image-to-image blend): /mj/submit/blend
- Describe task (image-to-text): /mj/submit/describe
- Shorten task (prompt analysis): /mj/submit/shorten

### Category 2: Operate on an Existing Task

- Action task (UPSCALE, VARIATION, REROLL, ZOOM, etc.): /mj/submit/action
- Modal task (inpainting, zoom, and related modal actions): /mj/submit/modal

### Category 3: Query a Task

- Fetch a task by ID: /mj/task/{id}/fetch

## Integration Flow Demo

### Step 1: Submit an Imagine Task

~~~bash
curl --request POST \
  --url {{BASE_URL}}/fast/mj/submit/imagine \
  --header 'Authorization: Bearer sk-your-key' \
  -H "Content-Type: application/json" \
  --data '{
    "base64Array": [],
    "prompt": "black cat"
  }'
~~~

The response result field is the task ID.

### Step 2: Query the Task Result by Task ID

~~~bash
curl --request GET \
  --url {{BASE_URL}}/fast/mj/task/1320098173412546/fetch \
  --header 'Authorization: Bearer sk-your-key' \
  -H "Content-Type: application/json"
~~~

Poll until progress reaches 100%.

### Step 3: Click a Returned Button Through the Action Endpoint

The query response returns a buttons array. Pass the corresponding customId into /mj/submit/action.

~~~json
{
  "customId": "MJ::JOB::upsample::2::3dbbd469-36af-4a0f-8f02-df6c579e7011",
  "taskId": "14001934816969359"
}
~~~

### Step 4: Query the Result Again

Repeat the same fetch flow until the follow-up task finishes. You can then continue with more actions if needed.

## Interface Summary

### Imagine

- endpoint: /mj/submit/imagine
- request method: POST
- request type: application/json
- key request fields: base64Array, prompt
- response includes code, description, properties, and result (task ID)

### Blend

- endpoint: /mj/submit/blend
- used when you want to blend multiple image inputs
- key request fields include base64Array and dimensions

### Describe

- endpoint: /mj/submit/describe
- used to generate text prompts from an image

### Shorten

- endpoint: /mj/submit/shorten
- used to analyze and shorten prompts

### Action

- endpoint: /mj/submit/action
- used for operations such as UPSCALE, VARIATION, REROLL, ZOOM, PAN, and related follow-up actions

### Modal

- endpoint: /mj/submit/modal
- used for modal-style interactions such as inpainting or zoom configuration

### Fetch

- endpoint: /mj/task/{id}/fetch
- used to inspect task progress, result images, returned buttons, failure reasons, and timestamps

## Notes

- buttons contains the follow-up actions currently available for the task
- status can move through states such as NOT_START, SUBMITTED, MODAL, IN_PROGRESS, FAILURE, and SUCCESS
- progress shows task progress
- failReason explains failures when present