Skip to main content
Glama

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "model": "<model>",
      "scene": "<scene>",
      "items": "<items>"
    },
    "name": "start_batch"
  }
}

Input Schema

NameRequiredDescriptionDefault
itemsYesOne entry per picture: a Library image’s asset_id.
modelYes
sceneYes
promptNo
optionsNoOptions every run shares, as for generate; the picture field is filled per item.
project_idNo
idempotency_keyNo
notify_by_emailNo
expected_creditsNoThe quote you showed the person; a different price queues nothing.

Output Schema

NameRequiredDescriptionDefault
itemsYes
modelYes
sceneYes
countsYes
reusedYesAn earlier call with this idempotency_key started it.
statusYes
balanceYesCredits available when it was accepted.
batch_idYes
created_atYes
item_countYes
settled_atYes
quoted_creditsYesWhat the batch costs if every picture runs.
charged_creditsYesWhat its runs were charged so far.
per_item_creditsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / items / items / additionalProperties
      Added value: +false
  2. Changed6 schema fields changed
    • 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"
      +]
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations: nothing charged at submission, each run charged as it starts and refunded on failure, the whole quote must be covered by balance, and monthly-limited keys hold the full quote until each run completes or is cancelled/refused. It also discloses the asynchronous contract — a batch id returned at once — and the idempotency_key retry behavior. This is exactly the operational context the readOnlyHint/destructiveHint flags do not 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 core action before the sourcing and billing detail, and every clause carries real information. The billing sentence is long and clause-dense, but trimming it would lose genuinely decision-relevant constraints.

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?

An output schema exists and the description still explains the key return shape (a batch id returned immediately, tracked via get_batch). Combined with the billing and idempotency disclosure, an agent has what it needs to call this correctly; only the shared `options` object and project_id handling are left to the schema.

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?

Schema description coverage is only 33% across 9 parameters, and the description compensates well for the important ones: items is one entry per picture with a Library asset_id, model/scene must come from list_models `batches`, and expected_credits is the quote that blocks queueing if the price differs. It leaves prompt, options, project_id and notify_by_email unelaborated, so the coverage gap is only partly closed.

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 with scope: run the same model, scene and options once for each of several Library pictures. The worked example ('image to 3D for twelve product photos') plus the immediate contrast with per-picture sourcing from get_job/search_library makes it distinguishable from single-run siblings like generate.

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 concrete prerequisites: model and scene come from list_models (`batches`), asset_id from get_job or search_library on a finished image job. It also routes the follow-up to get_batch and tells the agent to pass idempotency_key on retries. It never explicitly says to use generate for a single picture, so the exclusion 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.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources