AI3D Studio

Start a batch over Library pictures

start_batch

Run the same model, scene and options once for each of several pictures in the account’s Library — for example image to 3D for twelve product photos. Take the scenes and models from list_models (batches), and each picture’s asset_id from get_job or search_library on a finished image job. Nothing is charged now: each run is charged as it starts and refunded if it fails, but the balance must cover the whole quote, and for a key or connection with a monthly limit the whole quote is held against it until each picture runs (then its real cost counts) or is cancelled, refused or refunded (then nothing does). Returns a batch id at once; follow it with get_batch. Pass idempotency_key on retries so a repeat returns the same batch instead of queueing another.

Input Schema

Name	Required	Description
`items`	Yes	One entry per picture: a Library image’s asset_id.
`model`	Yes
`scene`	Yes
`prompt`	No
`options`	No	Options every run shares, as for generate; the picture field is filled per item.
`project_id`	No
`idempotency_key`	No
`notify_by_email`	No
`expected_credits`	No	The quote you showed the person; a different price queues nothing.

Output Schema

Name	Required	Description
`items`	Yes
`model`	Yes
`scene`	Yes
`counts`	Yes
`reused`	Yes	An earlier call with this idempotency_key started it.
`status`	Yes
`balance`	Yes	Credits available when it was accepted.
`batch_id`	Yes
`created_at`	Yes
`item_count`	Yes
`settled_at`	Yes
`quoted_credits`	Yes	What the batch costs if every picture runs.
`charged_credits`	Yes	What its runs were charged so far.
`per_item_credits`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 24, 2026
- removedOutput schema / properties / items / items / properties / error_code / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / items / items / properties / error_code / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / items / items / properties / job_id / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / items / items / properties / job_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / settled_at / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / settled_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedOct 8, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes far beyond the annotations with a detailed charge model: nothing charged at creation, each run charged as it starts and refunded on failure, the full quote must be covered by balance, and monthly-limit keys hold the whole quote until each item runs or is cancelled/refused. Also discloses that a batch id is returned immediately and that idempotency_key makes retries safe, which is exactly the kind of context idempotentHint=false cannot convey.

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?

Front-loaded with the action and an example, then prerequisites, then cost behavior, then follow-up — a sensible ordering. The charging sentence is long and clause-heavy, and a bulleted cost/idempotency split would read faster, but nothing is wasted.

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

Completeness4/5

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

For a nested-array, 9-param, mutating tool this covers the hard parts: item limits, value sourcing, async follow-up, billing holds and retry safety, and an output schema means return shape needn't be spelled out. The unmentioned prompt and project_id leave a small but real hole.

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 33% schema coverage across 9 params, the description compensates well: it explains where model/scene values come from, that items are per-picture asset_ids, that options are shared across runs with the picture field filled per item, and what idempotency_key and the quoted price do. Gaps remain for prompt, project_id and notify_by_email, which are undocumented in both schema and description.

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 ('Run the same model, scene and options once for each of several pictures') and grounds it with a concrete example ('image to 3D for twelve product photos'). This makes the fan-out semantics immediately distinguishable from the single-run 'generate'/'generate_3d' siblings 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 Guidelines4/5

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

Gives explicit prerequisite routing: scenes and models come from list_models (`batches`), asset_ids from get_job or search_library on a finished image job, and the result is followed with get_batch. It never names 'generate' as the single-picture alternative, so the when-not-to-use case is implied rather than stated.

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?