> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Midjourney
> Premium AI image generation with text-to-image, image-to-image, image-edit, variation, upscale, reroll, and enhance workflows
## Overview
Midjourney is an async image model for high-quality diffusion generation, source-image-guided generation, region editing, variation, upscaling, reroll, and draft enhancement. Use this page when you are ready to call the API after trying Midjourney in the APIXO playground.
| Capability | Value |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model ID | `midjourney` |
| Modes | `text-to-image`, `image-to-image`, `image-edit`, `vary`, `upscale`, `reroll`, `enhance` |
| Prompt length | Non-empty. Route limits are up to 2000 characters or up to 7500 UTF-8 bytes; keep prompts under 2000 characters for portable requests. |
| Reference images | `text-to-image` supports up to 20 `image_urls` as image prompts. `image-to-image` requires at least one image reference field and still uses diffusion. `image-edit` requires exactly 1 source image for the edit base. |
| Aspect ratios | `1:1`, `1:2`, `2:1`, `2:3`, `3:2`, `3:4`, `4:3`, `5:6`, `6:5`, `9:16`, `16:9` |
| Speeds | `fast`, `turbo`, `draft`; `relaxed` is deprecated by the official provider. To maintain compatibility, we still accept this value, but it will be converted to `fast` for execution and billing. `draft` belongs to the diffusion family, so it is available for `text-to-image` and `image-to-image` when `version=7`. |
| Result count | Usually 4 images for generation and variation, usually 1 image for upscale and enhance |
## Workflow categories
| Category | Modes | Description |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Direct generation | `text-to-image`, `image-to-image`, `image-edit` | Submit a new task directly. `image-to-image` is the diffusion route with at least one required image reference. `image-edit` is the region editing workflow. |
| Secondary editing | `vary`, `upscale`, `reroll`, `enhance` | Operate on a previous Midjourney task result. `reroll` uses `taskId`. `vary`, `upscale`, and `enhance` use `taskId` plus `imageIndex`. `enhance` is only available for draft results. |
Do not put Midjourney inline flags such as `--ar`, `--style`, or `--sref` inside `prompt`. The backend strips prompt text from the first `--` onward. Use API fields such as `aspect_ratio`, `stylization`, `variety`, and `weirdness` instead.
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ---------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/midjourney` | Submit a Midjourney task |
| `GET` | `/statusTask/midjourney?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Copy-paste async quickstart
This minimal request submits a text-to-image task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/midjourney" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-image",
"prompt": "a cinematic product photo of a transparent speaker on black marble",
"version": "7",
"speed": "fast",
"aspect_ratio": "16:9",
"image_urls": [
"https://example.com/scene-reference.jpg"
],
"sref_urls": [
{
"url": "https://example.com/style-reference.jpg",
"weight": 2
}
],
"iw": 1.5,
"sw": 500,
"sv": 6,
"negative_prompt": "text, watermark"
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final result.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/midjourney?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/img1.png\",\"https://file.apixo.ai/img2.png\",\"https://file.apixo.ai/img3.png\",\"https://file.apixo.ai/img4.png\"]}",
"supported_actions": [
{
"mode": "reroll"
},
{
"mode": "vary",
"imageIndex_options": [0, 1, 2, 3],
"type_options": [0, 1]
},
{
"mode": "upscale",
"imageIndex_options": [0, 1, 2, 3],
"type_options": [0, 1, 2, 3]
},
{
"mode": "image-edit",
"imageIndex_options": [0, 1, 2, 3]
},
{
"mode": "enhance",
"imageIndex_options": [0, 1, 2, 3]
}
],
"createTime": 1767965610929,
"completeTime": 1767965652317,
"costTime": 41388
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "PromptInvalid",
"failMsg": "Prompt is invalid or rejected by provider",
"createTime": 1767965610929,
"completeTime": 1767965620132,
"costTime": 9203
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```
Use `data.supported_actions` directly when you want to present follow-up actions to users. It is returned at the same level as `resultJson` and is only present when follow-up operations are available.
The follow-up action set depends on the source task mode:
| Source mode | Follow-up modes |
| ---------------- | ---------------------------------------------------- |
| `text-to-image` | `reroll`, `vary`, `upscale`, `image-edit`, `enhance` |
| `image-to-image` | `reroll`, `vary`, `upscale`, `image-edit`, `enhance` |
| `image-edit` | `image-edit`, `upscale` |
| `vary` | `reroll`, `vary`, `upscale`, `image-edit` |
| `upscale` | `vary`, `image-edit` |
| `reroll` | `reroll`, `vary`, `upscale`, `image-edit`, `enhance` |
| `enhance` | `vary`, `upscale`, `image-edit` |
`enhance` is only returned for successful `v7 + draft` generation-family results. Follow-up actions that continue from a specific image can include `imageIndex_options` so clients can ask the user which image to continue from.
## Request body
### Text-to-image
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-image",
"prompt": "a quiet library inside a glass greenhouse, soft morning light",
"version": "7",
"speed": "fast",
"aspect_ratio": "16:9",
"image_urls": [
"https://example.com/scene-reference.jpg"
],
"sref_urls": [
{
"url": "https://example.com/style-reference.jpg",
"weight": 2
}
],
"iw": 1.5,
"sw": 500,
"sv": 6,
"negative_prompt": "text, watermark",
"stylization": 100,
"variety": 10,
"weirdness": 0
}
}
```
### Image-to-image
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-to-image",
"prompt": "a dog lying in a bright park with green grass and trees",
"image_urls": [
"https://example.com/dog-at-home.jpg"
],
"version": "7",
"speed": "fast",
"aspect_ratio": "4:3"
}
}
```
### Image-edit
Use `image-edit` when you want to edit a specific region. If `mask`, `canvas`, and `imgPos` are omitted on compatible routes, the backend can auto-fill a full-image edit region from `image_urls[0]`.
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "image-edit",
"prompt": "add a modern espresso machine on the counter",
"image_urls": [
"https://example.com/cafe.jpg"
],
"version": "7",
"speed": "fast",
"mask": {
"areas": [
{
"width": 1024,
"height": 1024,
"points": [320, 420, 700, 420, 700, 760, 320, 760]
}
]
},
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 1024,
"height": 1024,
"x": 0,
"y": 0
}
}
}
```
### Vary
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "vary",
"taskId": "task_previous_midjourney",
"imageIndex": 0,
"type": 1,
"remixPrompt": "more dramatic lighting and richer color contrast"
}
}
```
### Upscale
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "upscale",
"taskId": "task_previous_midjourney",
"imageIndex": 2,
"type": 0
}
}
```
### Reroll
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "reroll",
"taskId": "task_previous_midjourney"
}
}
```
### Enhance
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "enhance",
"taskId": "task_previous_midjourney",
"imageIndex": 1
}
}
```
## Parameters
Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
Midjourney input parameters.
Operation mode. Supported values: `text-to-image`, `image-to-image`, `image-edit`, `vary`, `upscale`, `reroll`, `enhance`.
Required for `text-to-image`, `image-to-image`, and `image-edit`. Must be non-empty. Route limits are up to 2000 characters or up to 7500 UTF-8 bytes; keep prompts under 2000 characters for portable requests.
Reference image URLs. For `text-to-image`, this field is optional and supports up to 20 image prompts. For `image-to-image`, at least one image reference field is required across `image_urls`, `sref_urls`, `cref_urls`, or `oref_urls`; if `image_urls` is used, it works as the direct image prompt input. For `image-edit`, it is required and must contain exactly 1 base image. URLs should be public, directly fetchable JPG, PNG, or WebP files.
Optional style reference images for `text-to-image`. Each item must contain `url` and can optionally contain `weight`. `weight` is a relative per-image weight, not a fixed-sum ratio.
Optional character reference images for `text-to-image`.
Optional object reference images for `text-to-image`. At most 1 image is allowed.
Midjourney model version. Use `7`, `6.1`, `6`, `8.1`, `niji6`, or `niji7` for current compatibility. The API also normalizes forms such as `v7`, `v6.1`, `v6`, `v8.1`, `niji 6`, and `niji 7`.
Required for `text-to-image`, `image-to-image`, and `image-edit`. Supported values: `relaxed`, `fast`, `turbo`, and `draft`. `relaxed` is deprecated by the official provider. To maintain compatibility, APIXO still accepts it, but it is converted to `fast` for execution and billing. `draft` is part of the diffusion family, so it is available for `text-to-image` and `image-to-image` when `version=7`. `image-edit` does not support `draft`.
Output aspect ratio. Supported values: `1:1`, `1:2`, `2:1`, `2:3`, `3:2`, `3:4`, `4:3`, `5:6`, `6:5`, `9:16`, `16:9`. When omitted, the upstream default is used.
Midjourney chaos/variation control. Supported range: `0`-`100`. One route defaults omitted values to `10`; other routes omit the flag unless you set it.
Artistic stylization strength. Supported range: `0`-`1000`. One route defaults omitted values to `1`; other routes omit the flag unless you set it.
Surreal or unconventional effect strength. Supported range: `0`-`3000`. One route defaults omitted values to `1`; other routes omit the flag unless you set it.
Image prompt weight for `text-to-image`. This field is only active when `image_urls` is provided.
Style reference weight for `text-to-image`. Supported range: `0`-`1000`. This field is only active when `sref_urls` is provided.
Character reference weight for `text-to-image`. Supported range: `0`-`100`. This field is only active when `cref_urls` is provided.
Object reference weight for `text-to-image`. Supported range: `1`-`1000`. This field is only active when `oref_urls` is provided.
Style reference version for `text-to-image`. This field is only active when `sref_urls` is provided.
Experimental parameter for `text-to-image`. Supported range: `0`-`100` on supported versions.
Negative prompt for `text-to-image`. This maps to Midjourney `--no`.
Optional quality setting. Supported values are version-specific.
Optional 2K HD switch. Only supported in `text-to-image` when `version` is `8.1`.
Optional raw mode switch for `text-to-image`. When `true`, the request adds Midjourney `--raw`.
Requests prompt translation to English. Translation behavior is route-dependent: some routes default to translation, while others only translate when the route is configured for it and this flag is `true`.
Optional watermark text. Supported on compatible routes.
Required for `vary`, `upscale`, `reroll`, and `enhance`. Use the APIXO task ID from a previous successful Midjourney generation task.
Required for `vary`, `upscale`, and `enhance`. Selects one image from the previous result. Supported range: `0`-`3`.
Optional transform type. For `vary`, `0` means subtle variation and `1` means strong variation. For `upscale`, supported values are `0`, `1`, `2`, and `3` on compatible routes.
Optional text guidance for `vary` on compatible routes. For `image-edit`, if `remixPrompt` is omitted, compatible routes reuse `prompt`.
Optional for `image-edit`. Use it when you need region-specific editing. If omitted on compatible routes, the backend can create a full-image mask from the source image.
Polygon edit regions. Each area can include `width`, `height`, and `points`. `points` is a flat coordinate array: `[x1,y1,x2,y2,...]`.
Black/white mask image URL or base64 mask. White areas are regenerated. Use either `areas` or `url`, not both.
Optional for `image-edit`. Canvas dimensions. If provided, `width` and `height` must be positive integers.
Canvas width in pixels.
Canvas height in pixels.
Optional for `image-edit`. Source image position and size on the canvas.
Image width in pixels.
Image height in pixels.
Horizontal offset from the canvas top-left corner.
Vertical offset from the canvas top-left corner.
`text-to-image` and `image-to-image` share the diffusion parameter family. `image-to-image` requires at least one image reference across `image_urls`, `sref_urls`, `cref_urls`, or `oref_urls`, while `text-to-image` treats `image_urls` as optional image prompts. `image-edit` is a separate region-editing workflow and uses `mask`, `canvas`, `imgPos`, and optional `remixPrompt`.
## Response format
### Submit task response
`POST /generateTask/midjourney` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique APIXO task identifier used with the status endpoint.
### Status response fields
Unique APIXO task identifier.
Current task state: `pending`, `processing`, `success`, or `failed`.
JSON string containing the generated image URLs. Present when `state` is `success`.
Optional follow-up actions for successful results. This field is returned at the same level as `resultJson` in `data`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds. Present after completion.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/midjourney" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "text-to-image",
"prompt": "a premium watch on dark stone, macro photography, soft reflections",
"version": "7",
"speed": "fast",
"aspect_ratio": "1:1"
}
}'
```
See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Midjourney is billed per use. The selected mode and speed determine the unit price.
The current public pricing is easiest to understand in two families:
| Category | Mode | APIXO price | Notes |
| ----------------- | ---------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Direct generation | `text-to-image` | `$0.10 / use` (`draft`), `$0.20 / use` (`fast`), `$0.40 / use` (`turbo`) | Diffusion generation. `v8.1` with `is_hd=true` and `fast` is `$0.30 / use`. |
| Direct generation | `image-to-image` | Same as `text-to-image` | Uses the same diffusion route as `text-to-image`, but requires at least one image reference input. |
| Direct generation | `image-edit` | `$0.30 / use` (`fast`), `$0.60 / use` (`turbo`) | Region editing workflow. |
| Secondary editing | `vary` | `$0.30 / use` | Requires a previous `taskId` and `imageIndex`. |
| Secondary editing | `upscale` | `$0.30 / use` | Requires a previous `taskId` and `imageIndex`. |
| Secondary editing | `reroll` | Same as the source task price | Re-runs the previous successful task with the same configuration. |
| Secondary editing | `enhance` | See [Pricing](https://apixo.ai/pricing) | Draft-only enhancement workflow. Requires a previous `taskId` and `imageIndex`. |
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Actual latency may vary by prompt complexity, mode, selected route, and current queue load.
| Mode or speed | Typical generation time | Recommended first poll | Poll interval |
| ------------------------------- | ---------------------------------------- | ----------------------- | ------------- |
| `turbo` generation | 15s-25s | 20s after task creation | 3s-5s |
| `fast` generation | 30s-45s | 20s after task creation | 3s-5s |
| `vary`, `upscale`, or `enhance` | 15s-60s | 15s after task creation | 3s-5s |
| `reroll` | Similar to the original generation speed | 20s after task creation | 3s-5s |
For high-concurrency production workloads, use callback mode to avoid frequent polling.
Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | ----------------------------------------------------------- | ------------------------------------------------ |
| `400` | Invalid request body, mode, parameter, prompt, or image URL | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Key or route cannot access the model | Check permissions and route strategy |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error | Retry with backoff |
| `502` | Upstream provider error | Retry with backoff |
| `504` | Upstream timeout | Retry or use callback mode for long-running jobs |
### Task failure codes
| Fail code | Meaning | What to do |
| ------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `PromptInvalid` | Prompt is invalid or rejected by the provider | Rewrite the prompt and remove unsafe or malformed content |
| `MissingParameter` | Required request parameters are missing | Check `mode`, `prompt`, `speed`, `image_urls`, `taskId`, and `imageIndex` |
| `SensitiveContentDetected` | Input or output was flagged by safety checks | Change the prompt or source image |
| `InputOutputSensitiveContentDetected` | The input or output was flagged as sensitive | Try different inputs |
| `Upload error` | Image upload or image size validation failed | Use a public direct image URL and keep image files within supported limits |
| `Website TimeOut` | MidJourney official website did not respond after multiple attempts | Retry later or use callback mode |
| `Task TimeOut` | The upstream task became outdated or timed out | Retry the generation |
| `RateLimitExceeded` | Upstream or APIXO rate limit was reached | Retry with exponential backoff |
### Common fixes
| Symptom | Fix |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Invalid mode type` | Use one of `text-to-image`, `image-to-image`, `image-edit`, `vary`, `upscale`, `reroll`, or `enhance`. |
| Parameter is ignored | Use stable API field names: `aspect_ratio`, `variety`, `stylization`, and `weirdness`. |
| Prompt unexpectedly loses flags | Move Midjourney flags out of `prompt`; text after the first `--` is stripped by the backend. |
| `taskId` not found for `vary`, `upscale`, `reroll`, or `enhance` | Use the APIXO task ID from a previous Midjourney result, not the upstream provider task ID. |
| Image-edit fails to read image size | Use a public, directly fetchable source image URL. The backend reads `image_urls[0]` to fill default canvas and mask values. |
| `relaxed` does not match expected execution speed or billing | `relaxed` is accepted for compatibility, but APIXO converts it to `fast` for execution and billing. |
| `draft` is rejected | `draft` is only supported in the diffusion family (`text-to-image` and `image-to-image`) when `version=7`. |
| `enhance` is rejected | `enhance` only works for successful Midjourney draft results. |
See [Error Codes](/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Routing Strategies](/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)