Create and save an image

image_generate · Gateway release 0.8.4 Generate exactly one standalone GPT Image in an authorized Storyworld and save it as Media. No Scene or asset draft is required. Existing billing applies. Save operationId before submitting; retry identical input with that ID after interruption, never buy an automatic replacement. Read image_request_get, then reference_image_preview using the retained assetId. Reference consent and approval are separate. Required scopes: account:read, studio:generate. 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

{
  "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."
    },
    "operationId": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9-]{16,128}$",
      "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."
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "pattern": "\\S"
    },
    "aspect": {
      "type": "string",
      "enum": [
        "1:1",
        "16:9",
        "9:16"
      ],
      "default": "1:1"
    }
  },
  "required": [
    "storyworldId",
    "operationId",
    "prompt"
  ]
}

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"
    },
    "requestedFrom": {
      "type": "string",
      "enum": [
        "studio",
        "mcp"
      ]
    },
    "storyworldId": {
      "type": "string",
      "pattern": "^[a-f0-9]{24}$"
    },
    "operationId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "preparing",
        "queued",
        "running",
        "completed",
        "failed",
        "cancelled",
        "needs_reconciliation"
      ]
    },
    "jobId": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[a-f0-9]{24}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "assetId": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[a-f0-9]{24}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "studioUrl": {
      "type": "string"
    },
    "prompt": {
      "type": "string"
    },
    "aspect": {
      "type": "string",
      "enum": [
        "1:1",
        "16:9",
        "9:16"
      ]
    },
    "evidence": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "submittedPrompt": {
              "type": "string"
            },
            "effectivePrompt": {
              "type": "string"
            },
            "requestedProvider": {
              "type": "string"
            },
            "requestedModel": {
              "type": "string"
            },
            "effectiveProvider": {
              "type": "string"
            },
            "effectiveModel": {
              "type": "string"
            },
            "aspect": {
              "type": "string",
              "enum": [
                "1:1",
                "16:9",
                "9:16"
              ]
            },
            "executionMode": {
              "type": "string",
              "enum": [
                "provider",
                "fake"
              ]
            }
          },
          "required": [
            "submittedPrompt",
            "effectivePrompt",
            "requestedProvider",
            "requestedModel",
            "effectiveProvider",
            "effectiveModel",
            "aspect",
            "executionMode"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "width": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "height": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "mimeType": {
      "type": [
        "string",
        "null"
      ]
    },
    "creditEstimate": {
      "type": [
        "number",
        "null"
      ]
    },
    "billingReceiptId": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    },
    "error": {
      "type": [
        "string",
        "null"
      ]
    },
    "nextActions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "schemaVersion",
    "requestedFrom",
    "storyworldId",
    "operationId",
    "status",
    "jobId",
    "assetId",
    "studioUrl",
    "prompt",
    "aspect",
    "evidence",
    "width",
    "height",
    "mimeType",
    "creditEstimate",
    "billingReceiptId",
    "createdAt",
    "updatedAt",
    "error",
    "nextActions"
  ],
  "additionalProperties": false
}

All tools · Permissions · Media and recovery

Start here

Create with Studio

Reference

Workflow tools

Create and save an image

Input

Declared output

​Input

​Declared output

Input

Declared output