Use your studio anywhere.
Generate on the Spark from a script, another app, or a ComfyUI workflow. The client sends a prompt over HTTP and receives an image. All MiniMax inference stays on this server.
__BASE_URL____BASE_URL__/v1Connect & authenticate
Ask the studio owner for the API key. It is separate from the browser sign-in password. Set it in your client environment and send it as a bearer token on every API request.
export H3_STUDIO_API_KEY='YOUR_API_KEY'curl --fail-with-body '__BASE_URL__/api/status' \
-H "Authorization: Bearer $H3_STUDIO_API_KEY"A ready model returns {"ready": true, "queued": 0, "running": false}. GET /health checks the web app only; use /api/status to check the model. Use the studio port, 8088, for integrations. The raw model port is private.
Use the address reachable from the machine running your client. For ComfyUI, that means its Python server, which may be on a different machine from your browser. When accessing the studio through a public domain, use its HTTPS URL.
Generate an image
POST /v1/images/generations waits for the queued request and returns the PNG in data[0].b64_json. This is an OpenAI-style Images endpoint, with the model-specific parameters listed below.
curl --fail-with-body '__BASE_URL__/v1/images/generations' \
-H "Authorization: Bearer $H3_STUDIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MiniMaxAI/MiniMax-H3-Image",
"prompt": "A quiet London street after rain, warm shop lights reflected on the pavement, detailed photograph",
"size": "2048x2048",
"seed": 42,
"response_format": "b64_json"
}' -o response.json
python -c 'import base64,json; from pathlib import Path; Path("image.png").write_bytes(base64.b64decode(json.load(open("response.json"))["data"][0]["b64_json"]))'Allow enough time for other queued requests, especially for 4K images. The synchronous API waits up to 40 minutes; a proxy or client may time out earlier. The asynchronous job API below avoids a long open connection.
Queued jobs
The studio processes one image at a time and allows up to eight waiting jobs. All API calls below require the same bearer key.
| Endpoint | Use |
|---|---|
POST /api/jobs | Send the same generation JSON. HTTP 202 returns a job object with id and status. |
GET /api/jobs/{id} | Poll every 1–2 seconds. Status is queued, running, succeeded, or failed. |
GET /api/jobs/{id}/image | After success, download the PNG directly. |
DELETE /api/jobs/{id} | Permanently remove a completed image and its job record from the shared library. HTTP 204 on success; queued/running jobs return 409. |
GET /api/jobs | List recent jobs. All authorized studio users share this library. |
GET /api/status | Check model readiness and current queue size. |
Completed images are retained for the last 50 jobs. Download results you want to keep. If a connection drops after submission, check the existing job before submitting again; it may still complete. Restarted in-flight jobs are marked failed rather than resubmitted.
Supported parameters
| Field | Default / accepted values |
|---|---|
prompt | Required, nonblank, up to 16,000 characters. Describe the complete scene. |
model | MiniMaxAI/MiniMax-H3-Image. May be omitted. |
size | 2048x2048. Each dimension must be a multiple of 32, between 512 and 6272; at most 18 million pixels. |
seed | Random when omitted; integer from 0 to 4294967295. |
quality | lossless or exact. Default lossless. Both use the configured MXFP8 weights. |
n | Always 1. |
num_inference_steps | Always 6. |
generator_device | Always cpu. |
response_format | Always b64_json on the synchronous endpoint. |
Useful sizes: 2048x2048, 4096x4096, 4736x3552, 3552x4736, and 5472x3072. Outputs smaller than 2048² still use a larger generation canvas before resizing.
quality=auto, standard, or high need adjustment; use the included ComfyUI adapter for the supported request format.Use it in ComfyUI
The included custom node calls this studio's HTTP API, polls the job, and returns an IMAGE output. ComfyUI does not download or load MiniMax weights. Use the output with Save Image, Preview Image, or another image-processing node.
- Extract the ZIP so the file is at
ComfyUI/custom_nodes/comfyui_h3_studio/__init__.py. The ZIP already contains thecomfyui_h3_studiofolder; avoid nesting that folder twice. - Set
H3_STUDIO_API_KEYin the environment that starts the ComfyUI server, using your studio API key. Restart ComfyUI after setting it. For Desktop, Docker, or a service, use that launcher's environment configuration. - Import the example workflow, or add Asset Factory → API → H3 Studio · Generate via API and connect its image output to Save Image.
- Set
api_baseto__BASE_URL__, with no/v1or/apisuffix. Use only a trusted studio URL; your API key is sent to it. - Start with 2048 × 2048, enter a prompt, and run the workflow. Set the seed's after-generate control to randomize for a new image each run, or fixed for repeatable inputs.
export H3_STUDIO_API_KEY='YOUR_API_KEY'
python main.py$env:H3_STUDIO_API_KEY = 'YOUR_API_KEY'
.\run_nvidia_gpu.batKeep the key in the server environment. It is not a node input and is never stored in the supplied workflow. The node uses Python's standard HTTP library plus NumPy, Pillow, and PyTorch from the existing ComfyUI installation; no extra package installation is needed for a normal ComfyUI environment.
ComfyUI may cache unchanged inputs. Change the seed or prompt to regenerate. Canceling a workflow stops this node from polling, but an already accepted server job continues. You can find its image in the studio library.
Give this to an agent
Copy this prompt into the coding agent on the computer running ComfyUI. It includes the actual studio address you are using here. The agent can install the adapter and build the workflow; you supply the API key through the ComfyUI launch environment.
Troubleshooting
| Symptom | What to check |
|---|---|
| 401 Unauthorized | Use the studio API key, not the sign-in password. Send Authorization: Bearer …. For ComfyUI, restart its Python server after configuring the environment. |
| 422 Validation error | Check size, steps, model, and quality. Remove unsupported fields. |
| 429 | The queue is full; wait before submitting another generation. |
| 502 / failed job | Check model readiness and studio logs. Inspect the job's error field. |
| 504 or network timeout | The accepted job may still finish. Check the library or poll its ID before retrying. |
| ComfyUI node missing | Check the folder path and ComfyUI's startup log, then restart the actual server process. |
| ComfyUI cannot connect | Test connectivity from the ComfyUI server host. Use the Spark's LAN address or your public HTTPS domain rather than another machine's localhost. |
The adapter follows ComfyUI's supported custom-node interface and IMAGE tensor format. The supplied file uses the documented workflow JSON format. Documentation and adapter downloads contain no credentials; generation and stored images require authentication.