# MidJourney Integration Guide

YutoAPI MidJourney capabilities are organized under "Image Models -> MidJourney". This page explains where to start and how a complete MidJourney task usually runs.

## Recommended Reading Order

1. Start with [Midjourney Integration Guide](/en/api/midjourney) to understand fast / relax modes, task types, polling, and button actions.
2. For your first image generation, use [Submit Imagine Task](/en/api/api-139393505).
3. After receiving a task ID, poll task status with [Fetch Task by ID](/en/api/api-139393493).
4. If the result contains `buttons`, send the selected `customId` and `taskId` to [Submit Action](/en/api/api-139393501) for upscale, variation, repaint, reroll, or zoom operations.

## Common Capabilities

| Scenario | Endpoint | Notes |
| --- | --- | --- |
| Text-to-image / image-guided image generation | `/mj/submit/imagine` | Main entry point for prompt-based generation with optional reference images. |
| Image blending | `/mj/submit/blend` | Blend multiple images into a new image. |
| Image description | `/mj/submit/describe` | Generate text descriptions from an image. |
| Prompt analysis | `/mj/submit/shorten` | Analyze or shorten prompts. |
| Button actions | `/mj/submit/action` | Run U, V, reroll, zoom, and related actions on an existing task. |
| Modal actions | `/mj/submit/modal` | Submit local repaint, zoom, or other actions that require modal parameters. |
| Task query | `/mj/task/{id}/fetch` | Poll task status, progress, image URL, and available buttons. |

## Minimal Flow

Step 1: submit an Imagine task:

```bash
curl --request POST \
  --url '{BaseURL}/mj/submit/imagine' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "base64Array": [],
    "prompt": "black cat, cinematic lighting"
  }'
```

The response contains a task ID, for example:

```json
{
  "code": 1,
  "description": "Submit success",
  "result": "1320098173412546"
}
```

Step 2: query the result with the task ID:

```bash
curl --request GET \
  --url '{BaseURL}/mj/task/1320098173412546/fetch' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

When `status` is `SUCCESS` and `progress` is `100%`, read `imageUrl` as the generated image. If the task fails, check `failReason` first.

Step 3: if you need upscale or variations, copy the target `customId` from the returned `buttons`:

```bash
curl --request POST \
  --url '{BaseURL}/mj/submit/action' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "taskId": "1320098173412546",
    "customId": "MJ::JOB::upsample::1::example"
  }'
```

Action endpoints also return a new task ID, which should be polled until completion.

## Notes

- Write prompts with clear subject, style, composition, aspect ratio, and constraints to reduce retries.
- MidJourney tasks are asynchronous. Do not wait for the final image in the submit request; poll the query endpoint instead.
- Use progressive polling intervals such as 2 seconds, 4 seconds, then 8 seconds to avoid excessive requests.
- fast and relax modes differ in cost and speed. Choose based on your business scenario.
- Do not put API keys in public frontend code, logs, GitHub, or screenshots.