# Midjourney API

This document describes the full workflow for calling Midjourney via Modelverse, including four operations: text-to-image generation, upscaling, variation, and reroll.

---

## Model List

| Model Name | Function |
|------------|----------|
| `midjourney-fast-imagine` | Text-to-image generation. Takes a prompt and returns a grid image composed of 4 images |
| `midjourney-fast-upscale` | Upscales a single image (U1~U4 and subsequent operations) |
| `midjourney-fast-variation` | Generates variations based on one image (V1~V4) |
| `midjourney-fast-reroll` | Regenerates all 4 images (🔄) |

---

## Service Endpoints

| API | Method | URL |
|-----|--------|-----|
| Submit Task | POST | `https://api-us-ca.umodelverse.ai/v1/tasks/submit` |
| Query Status | GET | `https://api-us-ca.umodelverse.ai/v1/tasks/status` |

Authentication: `Authorization: Bearer <your-api-key>`

---

## Workflow

All Midjourney tasks are executed **asynchronously**:

1. `POST /v1/tasks/submit` to submit a task and obtain `task_id`
2. Poll `GET /v1/tasks/status?task_id=<task_id>` until `task_status` becomes `Success` or `Failure`

---

## API Details

### Submit Task

**POST** `https://api-us-ca.umodelverse.ai/v1/tasks/submit`

#### Request Body

```json
{
  "model": "<model_name>",
  "input": {
    "prompt": "<prompt, required only for imagine>"
  },
  "parameters": {
    "mj_task_id": "<previous task_id, required for upscale / variation / reroll>",
    "mj_custom_id": "<custom_id from buttons, required for upscale / variation / reroll>"
  }
}
```

#### Parameter Description

| Field                     | Type   | Required                                  | Description                                         |
| ------------------------- | ------ | ----------------------------------------- | --------------------------------------------------- |
| `model`                   | string | Yes                                       | Model name, see the model list above                |
| `input.prompt`            | string | Required for imagine                      | Prompt for text-to-image generation                 |
| `parameters.mj_task_id`   | string | Required for upscale / variation / reroll | ID of the previous task                             |
| `parameters.mj_custom_id` | string | Required for upscale / variation / reroll | `custom_id` from `buttons` in the previous response |

#### Response

```json
{
  "output": {
    "task_id": "1775203239196609"
  },
  "request_id": "abc123..."
}
```

---

### Query Task Status

**GET** `https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>`

#### Response

```json
{
  "output": {
    "task_id": "1775203239196609",
    "task_status": "Success",
    "urls": ["https://...image_url..."],
    "submit_time": 1775203239,
    "buttons": [
      {"custom_id": "MJ::JOB::upsample::1::431a5822-...", "label": "U1"},
      {"custom_id": "MJ::JOB::upsample::2::431a5822-...", "label": "U2"},
      {"custom_id": "MJ::JOB::upsample::3::431a5822-...", "label": "U3"},
      {"custom_id": "MJ::JOB::upsample::4::431a5822-...", "label": "U4"},
      {"custom_id": "MJ::JOB::reroll::0::431a5822-...::SOLO", "emoji": "🔄"},
      {"custom_id": "MJ::JOB::variation::1::431a5822-...", "label": "V1"},
      {"custom_id": "MJ::JOB::variation::2::431a5822-...", "label": "V2"},
      {"custom_id": "MJ::JOB::variation::3::431a5822-...", "label": "V3"},
      {"custom_id": "MJ::JOB::variation::4::431a5822-...", "label": "V4"}
    ]
  }
}
```

#### task_status Enum

| Value     | Meaning                     |
| --------- | --------------------------- |
| `Pending` | Queued                      |
| `Running` | Generating                  |
| `Success` | Completed successfully      |
| `Failure` | Failed, see `error_message` |

#### Response Field Description

| Field                | Type    | Description                                                                                              |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `output.task_id`     | string  | Task ID                                                                                                  |
| `output.task_status` | string  | Task status (see enum above)                                                                             |
| `output.urls`        | array   | Image URLs. `imagine` / `variation` / `reroll` return one grid image; `upscale` returns one single image |
| `output.submit_time` | integer | Unix timestamp (seconds)                                                                                 |
| `output.buttons`     | array   | List of actionable buttons, each containing a `custom_id`                                                |

---

## Full Example

### Step 1 — Text-to-Image (imagine)

```bash
curl -X POST https://api-us-ca.umodelverse.ai/v1/tasks/submit \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-fast-imagine",
    "input": {
      "prompt": "a cute cat sitting on a cloud, anime style"
    }
  }'
```

After submission, poll the status endpoint until `task_status` becomes `Success`:

```bash
curl "https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=1775203239196609" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY"
```

Upon success, record:

* `urls[0]`: URL of the 4-image grid
* `task_id`: required for subsequent operations
* `buttons`: source of `custom_id` for further actions

---

### Step 2a — Upscale (example: U1)

Find the item in `buttons` where `label` is `"U1"` and extract its `custom_id`:

```bash
curl -X POST https://api-us-ca.umodelverse.ai/v1/tasks/submit \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-fast-upscale",
    "input": {},
    "parameters": {
      "mj_task_id":   "1775203239196609",
      "mj_custom_id": "MJ::JOB::upsample::1::431a5822-bfb2-4c55-8fc5-fc101abebd91"
    }
  }'
```

After successful upscale, the response will also include `buttons` with additional operations (e.g., further upscale, Vary, Zoom, Pan, Animate), which can all be triggered via the `midjourney-fast-upscale` model.

---

### Step 2b — Variation (example: V1)

Find the item in `buttons` where `label` is `"V1"` and extract its `custom_id`:

```bash
curl -X POST https://api-us-ca.umodelverse.ai/v1/tasks/submit \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-fast-variation",
    "input": {},
    "parameters": {
      "mj_task_id":   "1775203239196609",
      "mj_custom_id": "MJ::JOB::variation::1::431a5822-bfb2-4c55-8fc5-fc101abebd91"
    }
  }'
```

After variation succeeds, a new set of `buttons` will be returned, allowing further operations such as upscale.

---

### Step 2c — Reroll

Find the item in `buttons` where `emoji` is `"🔄"` and extract its `custom_id`:

```bash
curl -X POST https://api-us-ca.umodelverse.ai/v1/tasks/submit \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-fast-reroll",
    "input": {},
    "parameters": {
      "mj_task_id":   "1775203239196609",
      "mj_custom_id": "MJ::JOB::reroll::0::431a5822-bfb2-4c55-8fc5-fc101abebd91::SOLO"
    }
  }'
```