midjourney-imagine

Image Generation (client.imagine)

Signature

def imagine(
    self,
    prompt: str,
    *,
    image: str | None = None,        # image prompt (local path or URL)
    version: int = 7,                # model version
    wait: bool = True,               # poll until complete
    poll_interval: float = 5,        # seconds between polls
    timeout: float = 600,            # max wait seconds
    mode: str = "fast",              # speed mode: fast/relax/turbo
    **params,                        # version-specific params
) -> Job

Basic Usage

from midjourney_api import MidjourneyClient

with MidjourneyClient() as client:
    # Simple
    job = client.imagine("a red apple on a white table")

    # With parameters
    job = client.imagine(
        "cyberpunk city at night",
        ar="16:9",
        stylize=300,
        chaos=20,
    )

Available Parameters (**params)

Param	Type	Range	Description
ar	str	"w:h"	Aspect ratio (e.g., "16:9", "1:1")
stylize	int	0–1000	Stylization strength
chaos	int	0–100	Variation between results
quality	int	1, 2, 4	Render quality
seed	int	0–4294967295	Reproducibility seed
weird	int	0–3000	Unconventional aesthetics
stop	int	10–100	Early stopping percentage
no	str	free text	Negative prompt
tile	bool	—	Seamless tiling
raw	bool	—	Less stylized, more literal
draft	bool	—	Fast draft mode
niji	int	>= 1	Niji anime model (replaces --v)
sref	str	URL/path/code	Style reference
sw	int	0–1000	Style reference weight
oref	str	URL/path only	Object/character reference
ow	int	1–1000	Object reference weight
iw	float	0.0–3.0	Image prompt weight
personalize	str	code or ""	Personalization profile
speed	str	fast/relax/turbo	Speed mode (as param)
visibility	str	stealth/public	Visibility mode

Image Prompt

# URL
job = client.imagine("portrait in this style", image="https://example.com/ref.png")

# Local file (auto-uploaded)
job = client.imagine("portrait in this style", image="./reference.png")

The image URL is prepended to the prompt: "<url> portrait in this style --v 7".

Niji Mode

# Anime model — incompatible with oref, tile, quality
job = client.imagine("magical girl", niji=7, stylize=200)

Polling Behavior

# Default: wait for completion
job = client.imagine("hello")  # blocks until done
print(job.is_completed)  # True
print(job.image_urls)    # 4 CDN URLs

# Fire and forget
job = client.imagine("hello", wait=False)
print(job.status)  # "pending"
# Poll manually later via low-level API

Return Value

Job dataclass:

job.id            # str — job UUID
job.prompt        # str — full prompt with flags
job.status        # str — "completed" (if wait=True)
job.image_urls    # list[str] — 4 CDN URLs for grid images
job.is_completed  # bool — True when done
job.cdn_url(i)    # CDN URL for image index i

Internal Flow

1. Upload local files for image/sref/oref → CDN URLs
2. Build prompt: "<image_url> <prompt>" (if image given)
3. create_params(version=7, prompt=..., **params) → validates + builds typed params
4. api.submit_job(params, mode, metadata) → POST /api/submit-jobs
5. Poll api.get_job_status(job_id) until completed (if wait=True)
6. Return Job with populated image_urls

Errors

Exception	When
ValidationError	Invalid parameter value (range, format)
JobFailedError	Job rejected by Midjourney API
MidjourneyError	Timeout or HTTP error
AuthenticationError	Token expired / not set