# Whisper — canonical payload contracts

Speech-to-text (Whisper large-v3 CPU, default hu). Async: staging upload → whisper_job_start → whisper_job_status → whisper_job_result. Large file: POST /staging/upload (Bearer, multipart file) → pass response.url to whisper_job_start.

**Service id:** `whisper`  
**Docs:** [https://mcp.glc-rag.hu/guide/whisper](https://mcp.glc-rag.hu/guide/whisper)  
**Markdown docs:** [https://mcp.glc-rag.hu/guide/whisper.md](https://mcp.glc-rag.hu/guide/whisper.md)  
**MCP resource:** `docs://whisper/payload`

POST `https://mcp.glc-rag.hu/mcp`. Values below are **type slots** from the live input schema (e.g. `<string, required>`), not example data. Fill them from the user task.

RPC result wrapper: `result.structuredContent` is the object in **Output schema**. `result.isError` mirrors `structuredContent.is_error`.

## `whisper_job_start`

Start async speech-to-text. Returns {job_id} — not the transcript. Large local file: POST /staging/upload first, then pass response.url here. Then whisper_job_status → whisper_job_result. Default language hu.

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "whisper_job_start",
    "arguments": {
      "url": "<string, optional>",
      "content_base64": "<string, optional>",
      "filename": "<string, optional>",
      "language": "<string, optional, default 'hu'>",
      "task": "<string, optional, enum transcribe|translate, default 'transcribe'>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public https URL. Large/local files: POST /staging/upload → use returned url (https://mcp.glc-rag.hu/staging/…)."
    },
    "content_base64": {
      "type": "string",
      "description": "Tiny clips only. Large audio → /staging/upload."
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint (e.g. talk.mp3)."
    },
    "language": {
      "type": "string",
      "description": "Default hu. Use hu for Hungarian; auto to detect.",
      "default": "hu"
    },
    "task": {
      "type": "string",
      "enum": [
        "transcribe",
        "translate"
      ],
      "description": "transcribe (default) or translate (to English).",
      "default": "transcribe"
    }
  },
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Hex job id from whisper_job_start"
    },
    "status": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "job_id"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `whisper_job_status`

Poll whisper job. status: queued|running|completed|failed. Backoff 15–60s.

**Required arguments:** `job_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "whisper_job_status",
    "arguments": {
      "job_id": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "From whisper_job_start"
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Hex job id from whisper_job_start"
    },
    "status": {
      "type": "string"
    },
    "error": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "job_id",
    "status"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `whisper_job_result`

Transcript when status=completed. If still queued/running, keep polling status.

**Required arguments:** `job_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "whisper_job_result",
    "arguments": {
      "job_id": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "From whisper_job_start"
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Hex job id from whisper_job_start"
    },
    "status": {
      "type": "string"
    },
    "text": {
      "type": "string"
    },
    "language": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "job_id",
    "status"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```