AI3D Studio

Start a generation

generate

Start an async AI generation of any media type and return its job id. The input shape depends on the model (see list_models); for 3D prefer generate_3d. To run an image preset (list_models returns them: figurine, style, pose, convert), send mediaType "image", scene "image-to-image", options.image (the picture, or the subject then a reference), options.preset (its id) and optionally options.preset_addons and options.preset_background; the server composes the prompt, and prompt is then only your extra instructions. Bills credits: check the price with estimate_cost first. Pass a stable idempotencyKey when retrying — a retry with the same key replays the original job instead of billing twice. Then call get_job.

Input Schema

Name	Required	Description
`model`	Yes
`scene`	No
`prompt`	No	The prompt; with options.preset, only your additional instructions.
`options`	No	Model-specific options; derive from list_models (include_inputs). For an image preset: preset (its id), preset_addons, preset_background.
`mediaType`	Yes	Generation family, e.g. 'image' \| 'video' \| '3d' \| 'music' — see list_models.
`workflowType`	No
`idempotencyKey`	No
`expectedCredits`	No	The credits estimate_cost answered for this request. If the price has moved since, nothing is started or charged and the error (price_changed) gives the new price.

Output Schema

Name	Required	Description
`model`	Yes
`scene`	Yes
`job_id`	Yes	Pass to get_job to follow progress.
`status`	Yes	pending and processing are running; success, partial, failed and canceled are final. 'partial' means some outputs finished and the rest were refunded.
`deduped`	Yes	True when an earlier call with the same idempotency key already started this job: nothing was charged again.
`outputs`	Yes	How many results this job makes.
`media_type`	Yes
`credits_charged`	Yes	Credits taken from the balance.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 24, 2026
- removedOutput schema / properties / scene / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / scene / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed1 schema field changedOct 20, 2026

addedInput schema / properties / expectedCredits

Added value: +{
+  "description": "The credits estimate_cost answered for this request. If the price has moved since, nothing is started or charged and the error (price_changed) gives the new price.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

First observedOct 8, 2026

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds real behavioral context beyond the annotations: it bills credits, the call is async and returns a job id, retries with the same idempotencyKey replay the original job instead of double-billing, and a price_changed error starts nothing. Note that idempotentHint=false is not contradicted — the description explains that idempotency is opt-in via idempotencyKey, which reconciles with the annotation. What remains unstated is what a started-but-failed job means for credits and what the response envelope contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose, the sibling routing, and the billing/idempotency warnings are front-loaded, and the preset paragraph is genuinely necessary detail. The preset clause is a dense, comma-chained run-on that costs some readability, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, credit-billing, async tool with 8 parameters and a nested options object, the description covers routing, required call shape, cost safety, retry safety, and the next step. An output schema exists, so the absence of return-value detail is not a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 50% schema description coverage, the description carries real weight: it defines mediaType values ('image'), scene ('image-to-image'), the options.image ordering (picture, or subject then reference), options.preset/preset_addons/preset_background, and the narrowed meaning of prompt when a preset is used. It also explains idempotencyKey and the price_changed behavior of expectedCredits. model and workflowType are left implicit, which is the main gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Start an async AI generation of any media type') plus the concrete return ('return its job id'), and explicitly differentiates from the sibling generate_3d for 3D work. An agent can distinguish it from generate_3d, estimate_cost, and start_batch without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: consult list_models for the input shape, prefer generate_3d for 3D, call estimate_cost before this to check price, and call get_job afterwards. It also spells out the exact call shape for the image-preset case, so when-to-use is fully resolved rather than implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AI3D Studio tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?