Skip to content

Commit 7461d15

Browse files
authored
feat(ai): add MiniMax image generation (#59929)
1 parent 506ac20 commit 7461d15

12 files changed

Lines changed: 635 additions & 15 deletions

File tree

‎packages/ai/README.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -586,7 +586,9 @@ M2.x models always think, even when a disabling option is supplied. For tool con
586586
`response.message` in history before adding `Message.tool(...)` results; this preserves reasoning and any signatures.
587587

588588
The default API bases are `https://api.minimax.io/anthropic/v1` for Messages and `https://api.minimax.io/v1` for
589-
Chat and Responses. `configure({ baseURL })` replaces the selected API's base, including its version prefix.
589+
Chat, Responses and Images. `configure({ baseURL })` replaces the selected API's base, including its version prefix;
590+
use `https://api.minimax.cn/v1` for the mainland China platform. `minimax.image("image-01")` (also
591+
`@opencode/ai/providers/minimax/images`) generates images; see [MiniMax images](#minimax-images).
590592

591593
## Meta
592594

@@ -704,6 +706,7 @@ table before swapping only the `model`:
704706
| Meta | ✓ | ✓ (hint) | ignored | ✓ | `size`, `outputFormat` |
705707
| Z.ai | ✗ | width × height | width × height | ✗ | `size` |
706708
| Alibaba | ✓ | width × height | width × height | ✓ | `size`, `seed` |
709+
| MiniMax | ✓ | preset or w × h⁴ | preset or w × h⁴ | 1 (portrait subject) | `aspect_ratio`, `width`, `height`, `seed` |
707710
| Black Forest Labs | 1 | per model | width × height models | per model (1–8) | `width`, `height`, `seed`, `output_format`, `mask` |
708711
| fal | ✓ | per model | per model | 1 (several on `/edit`, `/multi`) | `image_size`, `seed`, `output_format`, `mask` |
709712
| Replicate | ✗ | ✗ | ✗ | ✗ (use `providerOptions`) | everything |
@@ -719,7 +722,8 @@ fixed sizes. `providerOptions.size` replaces `aspect` and `resolution`, so setti
719722
forwards `outputFormat` but does not apply it, so the returned bytes keep the upstream model's own format. ² Workers AI
720723
`@cf/black-forest-labs/flux-1-schnell` takes no size, and the provider rejects it. ³ Non-OpenAI gateway models
721724
(`bfl/flux-2-pro`) get a computed width × height, which the gateway passes through; models with a fixed list, such as
722-
Recraft, reject sizes outside it.
725+
Recraft, reject sizes outside it. ⁴ MiniMax sends its `aspect_ratio` preset for a preset aspect at about `1K` and an
726+
exact width × height (512–2048 px, steps of 8) otherwise; `image-01-live` takes only the presets, minus `21:9`.
723727

724728
`Media.Asset` is the one asset type shared by image requests, image responses, LLM messages, and tool results.
725729
`asset.source` is the serializable `Media.Source` (`bytes`, `base64`, `url`, or `ref`); `asset.bytes()`,
@@ -848,6 +852,26 @@ Z.ai does not include trustworthy MIME metadata for output URLs, so generated im
848852
`application/octet-stream` until materialized. Output URLs expire after 30 days; call `asset.materialize()` and
849853
persist the bytes promptly if they must remain available.
850854

855+
### MiniMax images
856+
857+
```ts
858+
import { MiniMax } from "@opencode/ai/providers"
859+
860+
const minimax = Image.generate({
861+
model: MiniMax.configure({ apiKey }).image("image-01"),
862+
prompt,
863+
n: 2,
864+
aspect: "16:9",
865+
images: [Media.url("https://example.com/portrait.jpg")], // optional subject reference
866+
providerOptions: { promptOptimizer: true, seed: 42 },
867+
})
868+
```
869+
870+
The reference image is sent as a `character` subject, so it should be a single front-facing portrait. Images come
871+
back inline (`responseFormat: "base64"` by default); `responseFormat: "url"` returns links that expire after 24 hours
872+
and carry no MIME type until materialized. MiniMax status codes map to typed errors; code 1026 is a `ContentPolicy`
873+
error.
874+
851875
### Partial images
852876

853877
OpenAI's GPT image models stream previews. `Image.stream` sends `stream: true` with `partialImages` (0–3, default 2)

‎packages/ai/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@
7979
"./providers/meta/responses": "./src/providers/meta/responses.ts",
8080
"./providers/minimax": "./src/providers/minimax.ts",
8181
"./providers/minimax/chat": "./src/providers/minimax/chat.ts",
82+
"./providers/minimax/images": "./src/providers/minimax/images.ts",
8283
"./providers/minimax/messages": "./src/providers/minimax/messages.ts",
8384
"./providers/minimax/responses": "./src/providers/minimax/responses.ts",
8485
"./providers/mistral": "./src/providers/mistral.ts",
Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
import { Duration, Effect, Schema } from "effect"
2+
import type { HttpClientResponse } from "effect/http"
3+
import { ImageModel, ImageResponse, type ImageRequestFor } from "../image.js"
4+
import { Media } from "../media.js"
5+
import { MediaProtocol } from "../route/media-protocol.js"
6+
import { MediaRoute } from "../route/media.js"
7+
import { AIError, QuotaExceededError, mergeJsonRecords, type OpenString } from "../schema/index.js"
8+
import { ProviderShared, optionalNull } from "./shared.js"
9+
import { ImageSizing } from "./utils/image-sizing.js"
10+
import { MediaInput } from "./utils/media-input.js"
11+
12+
const route = MediaProtocol.identity({ id: "minimax-images", name: "MiniMax Images", provider: "minimax" })
13+
export const DEFAULT_BASE_URL = "https://api.minimax.io/v1"
14+
export const PATH = "/image_generation"
15+
const OUTPUT_RETENTION = Duration.hours(24)
16+
17+
// ---------------------------------------------------------------------------
18+
// 1. Public model input
19+
// ---------------------------------------------------------------------------
20+
21+
/** Provider-native options. Common `aspect` and `resolution` lower to `aspect_ratio` or `width` and `height`. */
22+
export type MiniMaxImageOptions = {
23+
/** Defaults to `base64`, which returns the bytes inline; `url` links expire after 24 hours. */
24+
readonly responseFormat?: OpenString<"url" | "base64">
25+
readonly seed?: number
26+
readonly promptOptimizer?: boolean
27+
/** Native preset; it replaces `aspect` and `resolution`. */
28+
readonly aspect_ratio?: string
29+
/** Native size, 512 to 2048 in steps of 8 (`image-01` only); it replaces `aspect` and `resolution`. */
30+
readonly width?: number
31+
readonly height?: number
32+
} & Record<string, unknown>
33+
34+
export type Request = ImageRequestFor<MiniMaxImageOptions>
35+
36+
// ---------------------------------------------------------------------------
37+
// 2. Response schema
38+
// ---------------------------------------------------------------------------
39+
40+
const MiniMaxImageResponse = Schema.Struct({
41+
id: optionalNull(Schema.String),
42+
data: optionalNull(
43+
Schema.Struct({
44+
image_urls: optionalNull(Schema.Array(Schema.String)),
45+
image_base64: optionalNull(Schema.Array(Schema.String)),
46+
}),
47+
),
48+
metadata: optionalNull(
49+
Schema.Struct({
50+
success_count: optionalNull(Schema.Union([Schema.Number, Schema.String])),
51+
failed_count: optionalNull(Schema.Union([Schema.Number, Schema.String])),
52+
}),
53+
),
54+
base_resp: optionalNull(
55+
Schema.Struct({
56+
status_code: Schema.Number,
57+
status_msg: optionalNull(Schema.String),
58+
}),
59+
),
60+
})
61+
62+
const FAILURE: Readonly<Record<string, MediaProtocol.Failure>> = {
63+
1002: "RateLimit",
64+
1004: "Authentication",
65+
2013: "InvalidRequest",
66+
2049: "Authentication",
67+
}
68+
const INSUFFICIENT_BALANCE = 1008
69+
const CONTENT_POLICY = 1026
70+
71+
// ---------------------------------------------------------------------------
72+
// 5. Request body construction
73+
// ---------------------------------------------------------------------------
74+
75+
/** MiniMax's `aspect_ratio` presets and the sizes it renders them at. */
76+
const PRESETS: Record<string, ImageSizing.Size> = {
77+
"1:1": { width: 1024, height: 1024 },
78+
"16:9": { width: 1280, height: 720 },
79+
"4:3": { width: 1152, height: 864 },
80+
"3:2": { width: 1248, height: 832 },
81+
"2:3": { width: 832, height: 1248 },
82+
"3:4": { width: 864, height: 1152 },
83+
"9:16": { width: 720, height: 1280 },
84+
"21:9": { width: 1344, height: 576 },
85+
}
86+
87+
const LIMITS = { multiple: 8, minEdge: 512, maxEdge: 2048 }
88+
89+
const nativeOptions = (options: MiniMaxImageOptions = {}) => {
90+
const { responseFormat, promptOptimizer, ...native } = options
91+
return { response_format: responseFormat ?? "base64", prompt_optimizer: promptOptimizer, ...native }
92+
}
93+
94+
/** `image-01-live` rejects `21:9`. */
95+
const presets = (model: string) =>
96+
model === "image-01" ? PRESETS : Object.fromEntries(Object.entries(PRESETS).filter(([key]) => key !== "21:9"))
97+
98+
/** Presets render at about 1K, so they serve a preset aspect with no resolution or `1K`. */
99+
const preset = (request: Request) => {
100+
const aspect = request.aspect ?? "1:1"
101+
if (!Object.hasOwn(presets(request.model.id), aspect)) return undefined
102+
if (request.resolution !== undefined && ImageSizing.tier(request.resolution) !== 1) return undefined
103+
return aspect
104+
}
105+
106+
/** Only `image-01` takes free `width` and `height`; other models render the presets alone. */
107+
const sizing = (request: Request) => {
108+
if (!ImageSizing.isRequested(request)) return Effect.succeed({})
109+
const aspect = preset(request)
110+
if (aspect !== undefined) return Effect.succeed({ aspect_ratio: aspect })
111+
if (request.model.id === "image-01") return ImageSizing.exact(route, request, LIMITS)
112+
const available = presets(request.model.id)
113+
const closest = ImageSizing.nearest(request, Object.values(available))
114+
const name = Object.keys(available).find((key) => available[key] === closest)
115+
return Effect.fail(
116+
route.unsupported(
117+
request.resolution === undefined ? "media.aspect" : "media.resolution",
118+
`${request.model.id} can't render ${[request.aspect, request.resolution].filter((value) => value !== undefined).join(" at ")}; the closest size it takes is ${closest.width}x${closest.height} (${name}). Change aspect or resolution, or set aspect_ratio in providerOptions`,
119+
),
120+
)
121+
}
122+
123+
const isNativeSize = (options: MiniMaxImageOptions | undefined) =>
124+
options?.aspect_ratio !== undefined || options?.width !== undefined || options?.height !== undefined
125+
126+
// The API only takes a `character` (portrait) subject, one per request.
127+
const subject = (asset: Media.Asset) =>
128+
ProviderShared.mediaReference(asset, undefined, `${route.name} input`).pipe(
129+
Effect.map((item) => ({ type: "character", image_file: item.value })),
130+
)
131+
132+
const fromRequest = Effect.fn("MiniMaxImages.fromRequest")(function* (request: Request) {
133+
if ((request.images?.length ?? 0) > 1)
134+
return yield* route.unsupported("media.images", `${route.name} takes one subject reference image`)
135+
if (isNativeSize(request.providerOptions) && ImageSizing.isRequested(request))
136+
return yield* ProviderShared.invalidRequest(
137+
"MiniMax providerOptions aspect_ratio, width and height replace aspect and resolution; set one or the other",
138+
)
139+
const references = yield* Effect.forEach(request.images ?? [], subject)
140+
return MediaProtocol.json(
141+
mergeJsonRecords(
142+
{
143+
model: request.model.id,
144+
prompt: request.prompt,
145+
subject_reference: references.length === 0 ? undefined : references,
146+
n: request.n,
147+
...(yield* sizing(request)),
148+
},
149+
nativeOptions(request.providerOptions),
150+
request.http?.body,
151+
) ?? {},
152+
)
153+
})
154+
155+
// ---------------------------------------------------------------------------
156+
// 6. Response decoding
157+
// ---------------------------------------------------------------------------
158+
159+
const decodeDocument = route.decodeJson(MiniMaxImageResponse)
160+
161+
const decodeResponse = Effect.fn("MiniMaxImages.decodeResponse")(function* (
162+
response: HttpClientResponse.HttpClientResponse,
163+
) {
164+
const output = yield* decodeDocument(response)
165+
const decoded = output.value
166+
// MiniMax answers errors with HTTP 200 and a non-zero `base_resp.status_code`.
167+
const status = decoded.base_resp
168+
if (status && status.status_code !== 0) {
169+
const message = `${route.name} failed (${status.status_code}): ${status.status_msg ?? "unknown error"}`
170+
if (status.status_code === CONTENT_POLICY) return yield* output.contentPolicy(message)
171+
if (status.status_code === INSUFFICIENT_BALANCE)
172+
return yield* new AIError({ reason: new QuotaExceededError({ message, body: output.body, http: output.http }) })
173+
return yield* output.ended("failed", message, MediaProtocol.failure(FAILURE, status.status_code))
174+
}
175+
const images = [
176+
...(yield* Effect.forEach(decoded.data?.image_base64 ?? [], (data, index) =>
177+
MediaInput.decodedAsset(output.invalid, `${route.name} result ${index}`, data, undefined),
178+
)),
179+
// MiniMax returns no content type for URLs; the media type resolves when the asset is materialized.
180+
...(yield* Effect.forEach(decoded.data?.image_urls ?? [], (url) =>
181+
MediaProtocol.expiringUrl(url, OUTPUT_RETENTION),
182+
)),
183+
]
184+
const failed = Number(decoded.metadata?.failed_count ?? 0)
185+
if (images.length === 0 && failed > 0)
186+
return yield* output.contentPolicy(`${route.name} blocked ${failed} image(s) for content safety`)
187+
if (images.length === 0) return yield* output.invalid(`${route.name} returned no images`)
188+
return new ImageResponse({
189+
images,
190+
providerMetadata: {
191+
minimax: {
192+
id: decoded.id ?? undefined,
193+
successCount: decoded.metadata?.success_count ?? undefined,
194+
failedCount: decoded.metadata?.failed_count ?? undefined,
195+
},
196+
},
197+
})
198+
})
199+
200+
// ---------------------------------------------------------------------------
201+
// 7. Protocol and route
202+
// ---------------------------------------------------------------------------
203+
204+
export const protocol = MediaProtocol.inline<Request, ImageResponse>(route, {
205+
body: { from: fromRequest },
206+
response: { decode: decodeResponse },
207+
})
208+
209+
export const model = (input: MediaRoute.ModelInput) =>
210+
ImageModel.fromRoute<MiniMaxImageOptions>({ protocol, baseURL: DEFAULT_BASE_URL, path: PATH }, input)
211+
212+
export const MiniMaxImages = {
213+
protocol,
214+
model,
215+
} as const

‎packages/ai/src/providers/minimax.ts‎

Lines changed: 27 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
import { Effect, Schema } from "effect"
22
import type { ProviderPackage } from "../provider-package.js"
33
import { AnthropicMessages } from "../protocols/anthropic-messages.js"
4+
import { MiniMaxImages, type MiniMaxImageOptions } from "../protocols/minimax-images.js"
45
import { OpenAIChat } from "../protocols/openai-chat.js"
56
import { OpenResponses } from "../protocols/open-responses.js"
67
import { ProviderShared } from "../protocols/shared.js"
78
import { AuthOptions, type ProviderAuthOption } from "../route/auth-options.js"
89
import { Route, type RouteDefaultsInput } from "../route/client.js"
910
import { Endpoint } from "../route/endpoint.js"
1011
import { Framing } from "../route/framing.js"
12+
import { MediaRoute } from "../route/media.js"
1113
import { Protocol } from "../route/protocol.js"
12-
import { ProviderID, type LLMRequest, type ModelID } from "../schema/index.js"
14+
import { ProviderID, type LLMRequest, type ModelID, type ProviderOptions } from "../schema/index.js"
1315

1416
export const id = ProviderID.make("minimax")
1517

@@ -46,6 +48,8 @@ export type Settings<Options = MessagesOptionsInput> = ProviderPackage.Settings
4648
readonly baseURL?: string
4749
}
4850

51+
export type { MiniMaxImageOptions }
52+
4953
const ChatOptions = Schema.Struct({
5054
thinking: Schema.optional(Schema.Struct({ type: Schema.String })),
5155
reasoningSplit: Schema.optional(Schema.Boolean),
@@ -106,10 +110,11 @@ export const routes = [messagesRoute, chatRoute, responsesRoute]
106110

107111
export const configure = (input: Config = {}) => {
108112
const { apiKey: _apiKey, auth: _auth, baseURL, ...rest } = input
113+
const auth = AuthOptions.bearer(input, "MINIMAX_API_KEY")
109114
const defaults = {
110115
...rest,
111116
endpoint: baseURL === undefined ? undefined : { baseURL },
112-
auth: AuthOptions.bearer(input, "MINIMAX_API_KEY"),
117+
auth,
113118
}
114119
const messages = (modelID: string | ModelID) =>
115120
messagesRoute.with(defaults).model<MessagesOptionsInput>({ id: modelID })
@@ -120,25 +125,34 @@ export const configure = (input: Config = {}) => {
120125
})
121126
const responses = (modelID: string | ModelID) =>
122127
responsesRoute.with(defaults).model<ResponsesOptionsInput>({ id: modelID })
123-
return { id, model: messages, messages, chat, responses, configure }
128+
const media = MediaRoute.deployment(input, auth)
129+
const image = (modelID: string | ModelID, providerOptions?: ProviderOptions) =>
130+
MiniMaxImages.model({ ...media, id: modelID, providerOptions })
131+
return { id, model: messages, messages, chat, responses, image, configure }
124132
}
125133

126134
export const provider = configure()
127135

128-
export const model: ProviderPackage.Model<Settings<MessagesOptionsInput>, MessagesOptionsInput> = (
129-
modelID,
130-
{ apiKey, baseURL, body, headers, ...providerOptions }: Settings<MessagesOptionsInput> = {},
131-
) =>
132-
configure({
136+
export const model: ProviderPackage.Model<Settings<MessagesOptionsInput>, MessagesOptionsInput> = (modelID, settings) =>
137+
configure(config(settings)).model(modelID)
138+
export const imageModel = (modelID: string, settings?: Settings<MiniMaxImageOptions>) => {
139+
const input = config(settings)
140+
return configure(input).image(modelID, input.providerOptions)
141+
}
142+
143+
export const messages = provider.messages
144+
export const chat = provider.chat
145+
export const responses = provider.responses
146+
export const image = provider.image
147+
148+
function config({ apiKey, baseURL, body, headers, ...providerOptions }: Settings<{}> = {}) {
149+
return {
133150
apiKey,
134151
baseURL,
135152
headers,
136153
http: body === undefined ? undefined : { body },
137154
providerOptions,
138-
}).model(modelID)
139-
140-
export const messages = provider.messages
141-
export const chat = provider.chat
142-
export const responses = provider.responses
155+
}
156+
}
143157

144158
export * as MiniMax from "./minimax.js"
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import type { MiniMax } from "../minimax.js"
2+
3+
export { imageModel as model } from "../minimax.js"
4+
export type Settings = MiniMax.Settings<MiniMax.MiniMaxImageOptions>

‎packages/ai/test/exports.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import {
3636
Fireworks,
3737
Google,
3838
Meta,
39+
MiniMax,
3940
OpenCode,
4041
OpenAI,
4142
OpenAICompatible,
@@ -179,6 +180,8 @@ describe("public exports", () => {
179180
expect(Meta.provider.image).toBe(Meta.image)
180181
expect(ZAI.configure({ apiKey: "fixture" }).image("glm-image").route.id).toBe("zai-images")
181182
expect(ZAI.provider.image).toBe(ZAI.image)
183+
expect(MiniMax.configure({ apiKey: "fixture" }).image("image-01").route.id).toBe("minimax-images")
184+
expect(MiniMax.provider.image).toBe(MiniMax.image)
182185
expect(Alibaba.configure({ region: "ap-southeast-1", apiKey: "fixture" }).image("qwen-image-2.0").route.id).toBe(
183186
"alibaba-images",
184187
)

0 commit comments

Comments
 (0)