feiskyer/codex-settings / skills/minimax-image-skill
minimax-image-skill
VerifiedGenerate images when the user names MiniMax or image-01/image-01-live. Use the default image skill when no provider is named.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.9 KB |
| agents/openai.yaml | config | 259 B |
| minimax_image.pyexecutable | script | 9.7 KB |
| tests/test_minimax_image.py | script | 7.3 KB |
minimax_image.py
View on GitHub#!/usr/bin/env python3
"""Generate images from text with the MiniMax Image API."""
import argparse
import base64
import binascii
import json
import os
import sys
import uuid
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlparse
from urllib.request import Request, urlopen
API_ENDPOINTS = {
"global": "https://api.minimax.io/v1/image_generation",
"china": "https://api.minimaxi.com/v1/image_generation",
}
SUPPORTED_MODELS = ("image-01", "image-01-live")
SUPPORTED_ASPECT_RATIOS = ("1:1", "16:9", "4:3", "3:2", "2:3", "3:4", "9:16", "21:9")
DOWNLOAD_TIMEOUT_SECONDS = 60
MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024
def positive_int(value):
"""Parse a positive integer for argparse."""
parsed = int(value)
if parsed < 1:
raise argparse.ArgumentTypeError("must be a positive integer")
return parsed
def image_count(value):
"""Parse the API's supported image count range."""
parsed = positive_int(value)
if parsed > 9:
raise argparse.ArgumentTypeError("must be between 1 and 9")
return parsed
def image_dimension(value):
"""Parse an image dimension accepted by the API."""
parsed = positive_int(value)
if parsed < 512 or parsed > 2048 or parsed % 8:
raise argparse.ArgumentTypeError(
"must be between 512 and 2048 and divisible by 8"
)
return parsed
def build_parser():
parser = argparse.ArgumentParser(
description="Generate images from text with the MiniMax Image API"
)
parser.add_argument("--prompt", required=True, help="Text prompt for image generation")
parser.add_argument(
"--output",
default=None,
help="Output filename (default: minimax-image-<UUID>.png)",
)
parser.add_argument(
"--model",
choices=SUPPORTED_MODELS,
default="image-01",
help="Image model (default: image-01)",
)
parser.add_argument(
"--region",
choices=tuple(API_ENDPOINTS),
default="global",
help="API region (default: global)",
)
parser.add_argument(
"--aspect-ratio",
choices=SUPPORTED_ASPECT_RATIOS,
default=None,
help="Requested aspect ratio",
)
parser.add_argument("--width", type=image_dimension, default=None, help="Requested width")
parser.add_argument("--height", type=image_dimension, default=None, help="Requested height")
parser.add_argument("--seed", type=int, default=None, help="Generation seed")
parser.add_argument("--n", type=image_count, default=1, help="Number of images")
parser.add_argument(
"--response-format",
choices=("url", "base64"),
default="url",
help="API response format (default: url)",
)
parser.add_argument(
"--disable-prompt-optimizer",
action="store_true",
help="Disable prompt optimization",
)
return parser
def parse_args(argv=None):
args = build_parser().parse_args(argv)
args.prompt = args.prompt.strip()
if not args.prompt:
build_parser().error("--prompt must not be empty")
if len(args.prompt) > 1500:
build_parser().error("--prompt must not exceed 1500 characters")
if (args.width is None) != (args.height is None):
build_parser().error("--width and --height must be provided together")
args.output = args.output or f"minimax-image-{uuid.uuid4()}.png"
output_path = Path(args.output).expanduser()
if output_path.name in {"", ".", ".."}:
build_parser().error("--output must name a file")
if output_path.is_dir():
build_parser().error("--output must not be a directory")
args.output = output_path
return args
def build_payload(args):
payload = {
"model": args.model,
"prompt": args.prompt,
"response_format": args.response_format,
"n": args.n,
"prompt_optimizer": not args.disable_prompt_optimizer,
}
for field in ("aspect_ratio", "width", "height", "seed"):
value = getattr(args, field)
if value is not None:
payload[field] = value
return payload
def read_response(response):
data = response.read(MAX_DOWNLOAD_BYTES + 1)
if len(data) > MAX_DOWNLOAD_BYTES:
raise RuntimeError("API response exceeds the maximum allowed size")
try:
return json.loads(data.decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
raise RuntimeError("MiniMax returned an invalid JSON response") from exc
def response_count(metadata, field):
"""Parse a non-negative image count from response metadata."""
value = metadata.get(field)
if isinstance(value, bool):
raise TypeError(f"MiniMax response contained an invalid {field}")
try:
parsed = int(value)
except (TypeError, ValueError) as exc:
raise RuntimeError(f"MiniMax response contained an invalid {field}") from exc
if parsed < 0:
raise RuntimeError(f"MiniMax response contained an invalid {field}")
return parsed
def request_generation(args, api_key, opener=urlopen):
request = Request(
API_ENDPOINTS[args.region],
data=json.dumps(build_payload(args)).encode("utf-8"),
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with opener(request, timeout=DOWNLOAD_TIMEOUT_SECONDS) as response:
payload = read_response(response)
except HTTPError as exc:
raise RuntimeError(f"MiniMax request failed with HTTP {exc.code}") from exc
except URLError as exc:
raise RuntimeError(f"MiniMax request failed: {exc.reason}") from exc
base_response = payload.get("base_resp")
if isinstance(base_response, dict):
status_code = base_response.get("status_code")
if status_code not in (None, 0):
message = base_response.get("status_msg") or "unknown API error"
raise RuntimeError(f"MiniMax request failed: {message}")
data = payload.get("data")
image_values = data.get("image_urls") if isinstance(data, dict) else None
if not isinstance(image_values, list) or not image_values:
raise RuntimeError("MiniMax response did not contain any images")
if not all(isinstance(value, str) and value for value in image_values):
raise RuntimeError("MiniMax response contained an invalid image value")
metadata = payload.get("metadata")
if not isinstance(metadata, dict):
raise TypeError("MiniMax response did not contain image metadata")
success_count = response_count(metadata, "success_count")
response_count(metadata, "failed_count")
if success_count != len(image_values):
raise RuntimeError("MiniMax response image count did not match metadata")
return image_values
def output_path_for_result(output_path, index, multiple):
if multiple:
return output_path.with_name(
f"{output_path.stem}_{index + 1}{output_path.suffix}"
)
return output_path
def read_limited(response):
data = response.read(MAX_DOWNLOAD_BYTES + 1)
if len(data) > MAX_DOWNLOAD_BYTES:
raise RuntimeError("Downloaded image exceeds the maximum allowed size")
if not data:
raise RuntimeError("Downloaded image is empty")
return data
def download_image(url, opener=urlopen):
parsed = urlparse(url)
if parsed.scheme != "https" or not parsed.netloc:
raise RuntimeError("MiniMax returned an invalid image URL")
request = Request(url, headers={"Accept": "image/*"})
try:
with opener(request, timeout=DOWNLOAD_TIMEOUT_SECONDS) as response:
return read_limited(response)
except HTTPError as exc:
raise RuntimeError(f"Image download failed with HTTP {exc.code}") from exc
except URLError as exc:
raise RuntimeError(f"Image download failed: {exc.reason}") from exc
def decode_image(value):
encoded = value.split(",", 1)[1] if value.startswith("data:") and "," in value else value
try:
data = base64.b64decode(encoded, validate=True)
except (ValueError, binascii.Error) as exc:
raise RuntimeError("MiniMax returned invalid base64 image data") from exc
if not data:
raise RuntimeError("MiniMax returned empty base64 image data")
if len(data) > MAX_DOWNLOAD_BYTES:
raise RuntimeError("Decoded image exceeds the maximum allowed size")
return data
def save_images(image_values, output_path, response_format, opener=urlopen):
output_path = Path(output_path)
saved_paths = []
multiple = len(image_values) > 1
for index, value in enumerate(image_values):
target = output_path_for_result(output_path, index, multiple)
image_data = (
download_image(value, opener=opener)
if response_format == "url"
else decode_image(value)
)
target.parent.mkdir(parents=True, exist_ok=True)
target.write_bytes(image_data)
saved_paths.append(str(target))
return saved_paths
def run(args, api_key=None, api_opener=urlopen, download_opener=urlopen):
active_api_key = api_key or os.getenv("MINIMAX_API_KEY")
if not active_api_key:
raise RuntimeError("MINIMAX_API_KEY is required")
image_values = request_generation(args, active_api_key, opener=api_opener)
saved_paths = save_images(
image_values,
args.output,
args.response_format,
opener=download_opener,
)
for saved_path in saved_paths:
print(f"Image saved to: {saved_path}")
return saved_paths
def main(argv=None):
try:
return 0 if run(parse_args(argv)) else 1
except (OSError, RuntimeError, TypeError, ValueError) as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |