> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations: summer api models

> Run Summer API jobs from the agent: list models, estimate, run, batch and follow jobs. For each operation: what it does, whether it asks you first, its inputs and an example call.

Run Summer API jobs from the agent: list models, estimate, run, batch and follow jobs. 5 operations. How to call them, and what the answers mean: [Operations reference](https://docs.summerengine.com/mcp/operations.md).

> [!NOTE]
>
> Generated from the `summer-engine` npm package `4.8.0`: its public operation catalog (`registry/operations/public-catalog.json`) and its engine and local operations. If something here is wrong, the operation's definition is wrong.

| Operation | What it does | Asks you first |
| - | - | - |
| [`models.batch`](#batch) | Run up to 500 Summer API jobs at once, all or none, with the Summer sign-in; follow every job and save the files. | Not by default |
| [`models.estimate`](#estimate) | The exact USD price of one Summer API job before it runs, its breakdown and a quote id that holds the price for 15 minutes; charges nothing. | Never |
| [`models.job`](#job) | Read a Summer API job (state, price, assets and file URLs); follow it until it finishes and save its files on this computer. | Not by default |
| [`models.list`](#list) | The Summer API's curated game-dev models with capability, input schema, output formats, typical time and USD price; no sign-in. | Never |
| [`models.run`](#run) | Run one Summer API job into the person's Summer assets with the Summer sign-in; spends paid credits within the app's limit, can wait and save the files. | Not by default |

***

### batch

`models.batch`: **Batch**

> [!NOTE]
>
> Preview: search finds it and `summer_call` runs it. It may still change.

Run up to 500 Summer API jobs at once, all or none, with the Summer sign-in; follow every job and save the files.

| | |
| - | - |
| **MCP** | `summer_api_batch` in the npm MCP |
| **CLI** | `summer models batch` |
| **Runs** | On your computer, in the `summer-engine` npm package. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |
| **3.x names** | `summer_api_batch` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobs` | object\[] | No | Up to 500 jobs, all or none. Leave out with batchId. Items 1 to 500. |
| `jobs[].model` | string | Yes | A Summer API model id or alias from summer\_api\_models, e.g. 3d/default. Length 1 to 120. |
| `jobs[].input` | object | No | The model's input, matching its inputSchema from summer\_api\_models. |
| `jobs[].idempotencyKey` | string | No | This job's own key; by default the batch key and the job's position. Length 1 to 200. |
| `batchId` | string | No | Read a batch summer\_api\_batch answered, instead of starting one. Length 1 to 200. |
| `idempotencyKey` | string | No | Reuse to retry the same batch without queuing it twice. Length 1 to 200. |
| `wait` | boolean | No | Follow every job until it finishes (up to about a minute in this call). |
| `out` | string | No | A folder on this computer: save the finished job's files there (implies wait). Length 1 to …. |

> **Input JSON schema**
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "jobs": {
>       "type": "array",
>       "minItems": 1,
>       "maxItems": 500,
>       "items": {
>         "type": "object",
>         "properties": {
>           "model": {
>             "type": "string",
>             "minLength": 1,
>             "maxLength": 120,
>             "description": "A Summer API model id or alias from summer_api_models, e.g. 3d/default."
>           },
>           "input": {
>             "type": "object",
>             "additionalProperties": {},
>             "description": "The model's input, matching its inputSchema from summer_api_models."
>           },
>           "idempotencyKey": {
>             "type": "string",
>             "minLength": 1,
>             "maxLength": 200,
>             "description": "This job's own key; by default the batch key and the job's position."
>           }
>         },
>         "required": [
>           "model"
>         ],
>         "additionalProperties": false
>       },
>       "description": "Up to 500 jobs, all or none. Leave out with batchId."
>     },
>     "batchId": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 200,
>       "description": "Read a batch summer_api_batch answered, instead of starting one."
>     },
>     "idempotencyKey": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 200,
>       "description": "Reuse to retry the same batch without queuing it twice."
>     },
>     "wait": {
>       "type": "boolean",
>       "description": "Follow every job until it finishes (up to about a minute in this call)."
>     },
>     "out": {
>       "type": "string",
>       "minLength": 1,
>       "description": "A folder on this computer: save the finished job's files there (implies wait)."
>     }
>   },
>   "additionalProperties": false
> }
> ```

**Example:** Batch

```json MCP theme={null}
{
  "name": "summer_api_batch",
  "arguments": {}
}
```

```bash CLI theme={null}
summer models batch
```

***

### estimate

`models.estimate`: **Estimate**

> [!NOTE]
>
> Preview: search finds it and `summer_call` runs it. It may still change.

The exact USD price of one Summer API job before it runs, its breakdown and a quote id that holds the price for 15 minutes; charges nothing.

| | |
| - | - |
| **MCP** | `summer_api_estimate` in the npm MCP |
| **CLI** | `summer models estimate` |
| **Runs** | On your computer, in the `summer-engine` npm package. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |
| **3.x names** | `summer_api_estimate` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | A Summer API model id or alias from summer\_api\_models, e.g. 3d/default. Length 1 to 120. |
| `input` | object | No | The model's input, matching its inputSchema from summer\_api\_models. |

> **Input JSON schema**
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "model": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 120,
>       "description": "A Summer API model id or alias from summer_api_models, e.g. 3d/default."
>     },
>     "input": {
>       "type": "object",
>       "additionalProperties": {},
>       "description": "The model's input, matching its inputSchema from summer_api_models."
>     }
>   },
>   "required": [
>     "model"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Estimate

```json MCP theme={null}
{
  "name": "summer_api_estimate",
  "arguments": {}
}
```

```bash CLI theme={null}
summer models estimate
```

***

### job

`models.job`: **Job**

> [!NOTE]
>
> Preview: search finds it and `summer_call` runs it. It may still change.

Read a Summer API job (state, price, assets and file URLs); follow it until it finishes and save its files on this computer.

| | |
| - | - |
| **MCP** | `summer_api_job` in the npm MCP |
| **CLI** | `summer models job` |
| **Runs** | On your computer, in the `summer-engine` npm package. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |
| **3.x names** | `summer_api_job` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `jobId` | string | Yes | The job id summer\_api\_run answered. Length 1 to 200. |
| `wait` | boolean | No | Follow the job until it finishes (up to about a minute in this call). |
| `out` | string | No | A folder on this computer: save the finished job's files there (implies wait). Length 1 to …. |
| `cancel` | boolean | No | Ask to stop the job instead. Summer API jobs, queued or running, run to the end: the answer is unsupported. |

> **Input JSON schema**
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "jobId": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 200,
>       "description": "The job id summer_api_run answered."
>     },
>     "wait": {
>       "type": "boolean",
>       "description": "Follow the job until it finishes (up to about a minute in this call)."
>     },
>     "out": {
>       "type": "string",
>       "minLength": 1,
>       "description": "A folder on this computer: save the finished job's files there (implies wait)."
>     },
>     "cancel": {
>       "type": "boolean",
>       "description": "Ask to stop the job instead. Summer API jobs, queued or running, run to the end: the answer is unsupported."
>     }
>   },
>   "required": [
>     "jobId"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Job

```json MCP theme={null}
{
  "name": "summer_api_job",
  "arguments": {}
}
```

```bash CLI theme={null}
summer models job
```

***

### list

`models.list`: **List**

> [!NOTE]
>
> Preview: search finds it and `summer_call` runs it. It may still change.

The Summer API's curated game-dev models with capability, input schema, output formats, typical time and USD price; no sign-in.

| | |
| - | - |
| **MCP** | `summer_api_models` in the npm MCP |
| **CLI** | `summer models list` |
| **Runs** | On your computer, in the `summer-engine` npm package. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |
| **3.x names** | `summer_api_models` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `model` | string | No | One model id or alias; without it, every model. Length 1 to 120. |
| `capability` | "image" \| "3d" \| "video" \| "voice" \| "dialogue" \| "sound" \| "music" | No | Only this kind. |

> **Input JSON schema**
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "model": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 120,
>       "description": "One model id or alias; without it, every model."
>     },
>     "capability": {
>       "type": "string",
>       "enum": [
>         "image",
>         "3d",
>         "video",
>         "voice",
>         "dialogue",
>         "sound",
>         "music"
>       ],
>       "description": "Only this kind."
>     }
>   },
>   "additionalProperties": false
> }
> ```

**Example:** List

```json MCP theme={null}
{
  "name": "summer_api_models",
  "arguments": {}
}
```

```bash CLI theme={null}
summer models list
```

***

### run

`models.run`: **Run**

> [!NOTE]
>
> Preview: search finds it and `summer_call` runs it. It may still change.

Run one Summer API job into the person's Summer assets with the Summer sign-in; spends paid credits within the app's limit, can wait and save the files.

| | |
| - | - |
| **MCP** | `summer_api_run` in the npm MCP |
| **CLI** | `summer models run` |
| **Runs** | On your computer, in the `summer-engine` npm package. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |
| **3.x names** | `summer_api_run` |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | A Summer API model id or alias from summer\_api\_models, e.g. 3d/default. Length 1 to 120. |
| `input` | object | No | The model's input, matching its inputSchema from summer\_api\_models. |
| `quoteId` | string | No | From summer\_api\_estimate: refuse to charge more than it quoted. Length 1 to 600. |
| `idempotencyKey` | string | No | Reuse to retry the same run without running it twice. Length 1 to 200. |
| `wait` | boolean | No | Follow the job until it finishes (up to about a minute in this call). |
| `out` | string | No | A folder on this computer: save the finished job's files there (implies wait). Length 1 to …. |

> **Input JSON schema**
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "model": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 120,
>       "description": "A Summer API model id or alias from summer_api_models, e.g. 3d/default."
>     },
>     "input": {
>       "type": "object",
>       "additionalProperties": {},
>       "description": "The model's input, matching its inputSchema from summer_api_models."
>     },
>     "quoteId": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 600,
>       "description": "From summer_api_estimate: refuse to charge more than it quoted."
>     },
>     "idempotencyKey": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 200,
>       "description": "Reuse to retry the same run without running it twice."
>     },
>     "wait": {
>       "type": "boolean",
>       "description": "Follow the job until it finishes (up to about a minute in this call)."
>     },
>     "out": {
>       "type": "string",
>       "minLength": 1,
>       "description": "A folder on this computer: save the finished job's files there (implies wait)."
>     }
>   },
>   "required": [
>     "model"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Run

```json MCP theme={null}
{
  "name": "summer_api_run",
  "arguments": {}
}
```

```bash CLI theme={null}
summer models run
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.