Read retained Character media

character_media_read: permissions and generated input/output contracts.

character_media_read · Gateway release 0.8.3

Programmatic byte-range download of retained audition/video media after checking current Storyworld access. Prefer character_media_preview for conversation playback. Use a file adapter to keep base64 out of model context, pin generation across chunks and verify the final SHA-256. No generation, selection or billing.

Required scopes: account:read, studio:read. Read-only.

Availability depends on runtime configuration and the permissions granted to this connection. Use live MCP discovery as the authority.

​

Input

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "storyworldId": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{24}$",
      "description": "ID of an accessible saved Storyworld returned by discovery. Keep this destination fixed for the operation."
    },
    "characterId": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{24}$",
      "description": "ID of the exact saved Character to reuse; do not create a new identity for an outfit or accessory."
    },
    "assetId": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{24}$",
      "description": "ID of an already saved and linked Media record returned by this workflow."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Byte offset for programmatic download, starting at zero. Keep range bytes out of the chat transcript."
    },
    "length": {
      "type": "integer",
      "minimum": 1,
      "maximum": 524288,
      "description": "Maximum bytes in this programmatic range. Use character_media_preview for ordinary audition/video sharing."
    },
    "generation": {
      "type": "string",
      "pattern": "^[0-9]+$",
      "description": "Immutable storage generation from the first media range; reuse it for every subsequent range."
    }
  },
  "required": [
    "storyworldId",
    "characterId",
    "assetId"
  ]
}

​

Declared output

This is the declared success schema. Error results and binary media blocks are separate MCP protocol results.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "schemaVersion": {
      "type": "string",
      "const": "1"
    },
    "assetId": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$"
    },
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "mimeType": {
      "type": "string"
    },
    "totalBytes": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000000
    },
    "generation": {
      "type": "string",
      "pattern": "^\\d+$"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "nextOffset": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "dataBase64": {
      "type": "string",
      "maxLength": 699052
    }
  },
  "required": [
    "schemaVersion",
    "assetId",
    "sha256",
    "mimeType",
    "totalBytes",
    "generation",
    "offset",
    "nextOffset",
    "dataBase64"
  ],
  "additionalProperties": {}
}

All tools · Permissions · Media and recovery