midjourney-image-ref

Image References (image prompt, sref, oref)

Three reference types share the same upload flow but serve different purposes.

Reference Types

Type	Param	Weight	Weight Range	Default	Supports
Image prompt	image=	iw	0.0–3.0	1.0	URL, file
Style reference	sref=	sw	0–1000	100	URL, file, code
Object reference	oref=	ow	1–1000	100	URL, file only

Key constraint: oref accepts only image URLs/files — style codes are not supported. sref accepts URLs, local files, and style codes (short strings like "abc123").

Using with MidjourneyClient

Image Prompt

# URL
job = client.imagine("portrait", image="https://example.com/face.png")

# Local file (auto-uploaded to CDN)
job = client.imagine("portrait", image="./face.png")

# With weight
job = client.imagine("portrait", image="./face.png", iw=2.0)

Style Reference (sref)

# Style code
job = client.imagine("landscape", sref="abc123")

# URL
job = client.imagine("landscape", sref="https://example.com/style.png")

# Local file
job = client.imagine("landscape", sref="./style.png")

# With weight
job = client.imagine("landscape", sref="./style.png", sw=500)

Object Reference (oref)

# URL only (codes not supported)
job = client.imagine("character in forest", oref="https://example.com/char.png")

# Local file
job = client.imagine("character in forest", oref="./character.png")

# With weight
job = client.imagine("character in forest", oref="./character.png", ow=300)

Auto-Upload Flow

When a parameter value is a local file path (os.path.exists() returns True):

1. client._upload_if_local(value) is called
2. Uploads via api.upload_image(file_path) → POST /api/storage-upload-file
3. Returns CDN URL: https://cdn.midjourney.com/u/{bucketPathname}

See references/upload-flow.md for upload API details.

Using with V7Params (Low-Level)

For direct control, upload manually and construct typed parameters:

from midjourney_api.api import MidjourneyAPI
from midjourney_api.auth import MidjourneyAuth
from midjourney_api.params.types import StyleRef, StyleWeight, OmniRef, OmniWeight
from midjourney_api.params.v7 import V7Params

auth = MidjourneyAuth()
api = MidjourneyAPI(auth)

# Upload image manually
cdn_url = api.upload_image("./style.png")

# Build params with typed references
params = V7Params(
    prompt="cyberpunk city",
    sref=StyleRef(cdn_url),
    sw=StyleWeight(500),
)
params.validate()

job = api.submit_job(params, mode="fast", metadata={"imageReferences": 1})

Cross-Field Validation

• sw requires sref to be set → ValidationError("sw requires sref to be set")
• ow requires oref to be set → ValidationError("ow requires oref to be set")
• niji is incompatible with oref → ValidationError("oref not compatible with niji")

Prompt Assembly

Image prompt is prepended to the text prompt:

"https://cdn.midjourney.com/u/.../ref.png cyberpunk city --v 7 --ar 16:9"

Style and object references are appended as flags:

"cyberpunk city --v 7 --sref https://cdn.../style.png --sw 100 --oref https://cdn.../char.png --ow 100"