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

# Retain an incoming Studio reference

> reference_image_upload: permissions and generated input/output contracts.

`reference_image_upload` · Gateway release **0.8.3**

Upload an original PNG/JPEG/WebP up to 3 MiB and retain source, usage statement and verified byte hash. Use the local Codex upload helper so base64 stays out of model context. Source declarations are recorded as this MCP client acting for the connected account, never as a separate human review. No URL fetch or generation. Retry the same operationId and identical file/source.

Required scopes: `account:read`, `studio:write`. Changes saved state or requests work; review the operation’s effects.

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

## Input

```json theme={null}
{
  "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."
    },
    "purpose": {
      "type": "string",
      "enum": [
        "character",
        "location",
        "artifact"
      ]
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "operationId": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9-]{16,64}$",
      "description": "Persist a client-generated UUID before this mutation. Repeat identical inputs and this same ID after interruption; a new ID is a new request."
    },
    "mimeType": {
      "type": "string",
      "enum": [
        "image/png",
        "image/jpeg",
        "image/webp"
      ]
    },
    "fileBase64": {
      "type": "string",
      "minLength": 4,
      "maxLength": 4194304,
      "description": "Programmatic upload bytes only. Use a host attachment adapter; never compose base64 in model text. Otherwise upload in Studio and reuse its saved asset ID."
    },
    "source": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "rightsBasis": {
          "type": "string",
          "enum": [
            "creator_owned",
            "licensed",
            "consented",
            "public_domain",
            "other"
          ]
        },
        "rightsConfirmed": {
          "type": "boolean",
          "const": true,
          "description": "True only with a valid creator/rights declaration for the supplied source. Never invent consent."
        },
        "provider": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "modelId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "prompt": {
          "type": "string",
          "minLength": 1,
          "maxLength": 16000
        },
        "rightsStatement": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        }
      },
      "required": [
        "provider",
        "rightsStatement",
        "rightsBasis",
        "rightsConfirmed"
      ]
    }
  },
  "required": [
    "storyworldId",
    "title",
    "operationId",
    "mimeType",
    "fileBase64",
    "source"
  ]
}
```

## Declared output

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

```json theme={null}
{
  "$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}$"
    },
    "storyworldId": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$"
    },
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "mimeType": {
      "type": "string"
    },
    "sourceRecorded": {
      "type": "boolean",
      "const": true
    },
    "sourceRecordId": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "sourceDeclarationSha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "sourceRecordLocation": {
      "type": "string",
      "const": "mcp_operation"
    },
    "assetProvenancePreserved": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "schemaVersion",
    "assetId",
    "storyworldId",
    "sha256",
    "mimeType",
    "sourceRecorded",
    "sourceRecordId",
    "sourceDeclarationSha256",
    "sourceRecordLocation",
    "assetProvenancePreserved"
  ],
  "additionalProperties": {}
}
```

[All tools](https://docs.sia.vision/mcp-reference.md) · [Permissions](https://docs.sia.vision/authentication.md) · [Media and recovery](https://docs.sia.vision/media-and-recovery.md)


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