--- title: "generate_image" description: "Generated reference for the management action generate_image: its description, access metadata, payload contract, and registration status." slug: /reference/actions/generate-image order: 81 visibility: public redirects_from: [] --- # generate\_image Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources). A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/generate_image`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `generate_image`. **Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured. ## Contract description Generate one image from a prompt and save it in your application's storage, in the area `images-`\. No deployed code is needed\. If your account has no application, call `create_application` first\. Nothing is saved or counted if the application's stored data is over its limit\. During the introductory period, each account has 20 images per UTC month\. `read_account` shows their use under your own sign\-in, including an authorized computer's token\. A saved picture's result gives its address and normally two download commands, `commands.curl` and `commands.powershell`, which work for five minutes\. If no grant could be created, the picture stays saved and counted, the commands are absent, and `detail` says how else to read it\. On MCP, pass `inline: true` to receive a saved picture as image content if it is at most 256 KiB\. A larger picture stays in storage for a command to fetch\. Past 45 seconds, the call fails and stays counted; a repeat uses another image\. ## More about this action Pass `application` and `prompt`, and optionally `environment`, `resolution`, and `inline`\. The file goes to the environment you pass, or otherwise to the application's deploy target: production with one environment, development with two\. `resolution` is `1K`, the default, or `2K`\. The platform calls one model and uses none of an application's AI allowance\. The files stay in the application's storage until deleted\. The platform chooses each file's name, so a repeat does not replace an earlier picture\. Each download command sends a read\-only grant for this one file until `expires_at`; a read does not use it up\. If no grant could be created, the commands and `expires_at` are absent\. Read `detail` for the other way to fetch the saved file\. A picture larger than 256 KiB reaches a host with no shell only through a tool that can run a command\. A signed\-in connection and an account\-wide token may call this tool\. An application's platform credential, a token restricted to one application, a token restricted by a grant, and a device sign\-in cannot\. A provider block returns `blocked: true` with the reason, counts, and writes no file\. A provider refusal before any picture normally gives the image back\. If that fails, it stays counted, and the refusal's `detail` says so\. A saved picture or a provider block includes `used`, `cap`, and `resets_at`, the first instant of the next UTC month\. A token minted for a job does not receive `read_account`'s `image_generation` member\. ## Access and action metadata ```json { "name": "generate_image", "resource": "account", "tier": "reversible", "surface": "account", "summary": "Generate one image from a prompt and save it in the application's storage. Pass `application`, an identifier from `list_applications`, and `prompt`. With no application, call `create_application` first. The application needs no deployed code.\n\nThe file goes to `images-`, which the platform creates where absent. Pass `environment`, or use the application's deploy target. Its bytes count in the application's stored data. If that data is already over its limit, the call returns `usage_over_quota` before saving or counting anything.\n\nDuring the introductory period, each account has 20 images per UTC month. At the cap, `image_cap_reached` includes `used`, `cap`, and `resets_at`. `image_generation_unavailable` means the platform cannot make images now; with no key stored, its detail says image generation is coming soon. It also covers an unreadable key, no current model price, the platform's monthly limit, or a provider refusal before any picture.\n\n`resolution` is `1K`, the default, or `2K`. The platform uses one model. The prompt reaches the provider; the platform stores only a digest of it.\n\nA saved picture's result includes its area, name, type, size, address, and the month's use. It normally includes two download commands, for a POSIX shell and Windows PowerShell, which send a read-only grant valid for five minutes. If the grant cannot be created, the picture stays saved and counted, no commands are included, and `detail` says how else to read it.\n\nWith `inline: true`, a saved picture also appears as MCP image content if it is at most 256 KiB. A larger picture stays in storage. A provider block returns `blocked: true` with the reason, counts, and saves no file. A provider refusal before any picture normally gives the image back; if that fails, the refusal says it stays counted. Past 45 seconds, the call fails and stays counted; a repeat uses another image.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": true } } ``` ## MCP catalog entry ```json { "name": "generate_image", "title": "Generate an image", "tier": "reversible", "scenario": "ACB-L0-93", "summary": "Generate one image from a prompt and save it in your application's storage, in the area `images-`. No deployed code is needed. If your account has no application, call `create_application` first. Nothing is saved or counted if the application's stored data is over its limit.\n\nDuring the introductory period, each account has 20 images per UTC month. `read_account` shows their use under your own sign-in, including an authorized computer's token.\n\nA saved picture's result gives its address and normally two download commands, `commands.curl` and `commands.powershell`, which work for five minutes. If no grant could be created, the picture stays saved and counted, the commands are absent, and `detail` says how else to read it.\n\nOn MCP, pass `inline: true` to receive a saved picture as image content if it is at most 256 KiB. A larger picture stays in storage for a command to fetch. Past 45 seconds, the call fails and stays counted; a repeat uses another image.", "owners": [ "ACB-L0-93", "PRC-L0-18", "MCP-08", "OST-L0-01", "OST-L0-08", "API-L0-17", "SEC-L0-07", "PLD-L0-96" ] } ``` ## request | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["prompt"\] | | /properties/application | Required: the id of the application whose storage receives the image, from `list_applications`\. With none in the account, call `create_application` first\.

Type: string | | /properties/environment | The environment whose partition receives the file; absent, the application's deploy target\. One the application does not have is refused `environment_not_created`\.

Type: string
Pattern: ^\(development\|production\)$ | | /properties/prompt | What to draw\. It is sent to the model's provider\. The platform keeps a digest of it and never the prompt\.

Type: string
Minimum length: 1
Maximum length: 8000 | | /properties/resolution | The image's size class; absent, `1K`\.

Type: string
Allowed values: \["1K","2K"\] | | /properties/inline | When true, a saved picture also appears as MCP image content if it is at most 256 KiB\. A larger file, or a call over HTTP, includes no image content; the result explains why\.

Type: boolean | ## response | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["contract\_version","application","model","resolution","used","cap","resets\_at","detail"\] | | /properties/contract\_version | Required value: 1 | | /properties/reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.

Type: string
Pattern: ^\[0\-9a\-f\]\{10\}$ | | /properties/application | The application whose storage received the image\.

Type: string | | /properties/model | The model the platform called\.

Type: string | | /properties/resolution | The size class the call asked for\.

Type: string | | /properties/used | The account's images counted this UTC month, this call among them\.

Type: integer | | /properties/cap | The account's images per UTC month\.

Type: integer | | /properties/resets\_at | The first instant of the next UTC month, as an ISO 8601 instant\.

Type: string | | /properties/blocked | True where the provider blocked the prompt or the picture: the call is counted, no file was written, and the file's members below are absent\.

Type: boolean | | /properties/reason | With `blocked`: the provider's reason, in its own words\.

Type: string | | /properties/environment | The partition the file is in\. Absent where `blocked`\.

Type: string | | /properties/area | The file's storage area, `images-`\. Absent where `blocked`\.

Type: string | | /properties/name | The file's name, which the platform chose\. Absent where `blocked`\.

Type: string | | /properties/mime\_type | The file's type\. Absent where `blocked`\.

Type: string | | /properties/bytes | The file's size\. Absent where `blocked`\.

Type: integer | | /properties/address | The file's whole address on the platform's public origin, each segment of its name escaped\. Absent where `blocked`\.

Type: string | | /properties/expires\_at | When the grant inside the commands stops serving, as an ISO 8601 instant\. Absent where `blocked`, or where no grant could be minted\.

Type: string | | /properties/commands | The two commands that download the file, each sending a read\-only grant as the bearer\. Absent where `blocked`, or where no grant could be minted, which `detail` then says\.

Type: object
Required fields: \["curl","powershell"\]
Additional properties: false | | /properties/commands/properties/curl | A curl command for a POSIX shell: the grant in the Authorization header, writing the file under its name in the folder it runs in\.

Type: string | | /properties/commands/properties/powershell | An Invoke\-WebRequest command for Windows PowerShell, with \-UseBasicParsing, which Windows PowerShell 5\.1 needs: the same header and the same file\.

Type: string | | /properties/inline | Present where the call passed `inline` true\.

Type: object
Required fields: \["returned"\]
Additional properties: false | | /properties/inline/properties/returned | Whether this answer carries the image as image content\.

Type: boolean | | /properties/inline/properties/reason | Where not returned: the image passes the bound, or the call did not arrive over MCP\.

Type: string | | /properties/detail | What happened and what to do next: the file's place and the commands' expiry, or the block's reason, with the month's use\.

Type: string | ## Complete payload contract ```json { "request": { "type": "object", "required": [ "prompt" ], "properties": { "application": { "type": "string", "description": "Required: the id of the application whose storage receives the image, from `list_applications`. With none in the account, call `create_application` first." }, "environment": { "type": "string", "pattern": "^(development|production)$", "description": "The environment whose partition receives the file; absent, the application's deploy target. One the application does not have is refused `environment_not_created`." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8000, "description": "What to draw. It is sent to the model's provider. The platform keeps a digest of it and never the prompt." }, "resolution": { "type": "string", "enum": [ "1K", "2K" ], "description": "The image's size class; absent, `1K`." }, "inline": { "type": "boolean", "description": "When true, a saved picture also appears as MCP image content if it is at most 256 KiB. A larger file, or a call over HTTP, includes no image content; the result explains why." } } }, "response": { "type": "object", "required": [ "contract_version", "application", "model", "resolution", "used", "cap", "resets_at", "detail" ], "properties": { "contract_version": { "const": 1 }, "reference": { "type": "string", "pattern": "^[0-9a-f]{10}$", "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call." }, "application": { "type": "string", "description": "The application whose storage received the image." }, "model": { "type": "string", "description": "The model the platform called." }, "resolution": { "type": "string", "description": "The size class the call asked for." }, "used": { "type": "integer", "description": "The account's images counted this UTC month, this call among them." }, "cap": { "type": "integer", "description": "The account's images per UTC month." }, "resets_at": { "type": "string", "description": "The first instant of the next UTC month, as an ISO 8601 instant." }, "blocked": { "type": "boolean", "description": "True where the provider blocked the prompt or the picture: the call is counted, no file was written, and the file's members below are absent." }, "reason": { "type": "string", "description": "With `blocked`: the provider's reason, in its own words." }, "environment": { "type": "string", "description": "The partition the file is in. Absent where `blocked`." }, "area": { "type": "string", "description": "The file's storage area, `images-`. Absent where `blocked`." }, "name": { "type": "string", "description": "The file's name, which the platform chose. Absent where `blocked`." }, "mime_type": { "type": "string", "description": "The file's type. Absent where `blocked`." }, "bytes": { "type": "integer", "description": "The file's size. Absent where `blocked`." }, "address": { "type": "string", "description": "The file's whole address on the platform's public origin, each segment of its name escaped. Absent where `blocked`." }, "expires_at": { "type": "string", "description": "When the grant inside the commands stops serving, as an ISO 8601 instant. Absent where `blocked`, or where no grant could be minted." }, "commands": { "type": "object", "required": [ "curl", "powershell" ], "properties": { "curl": { "type": "string", "description": "A curl command for a POSIX shell: the grant in the Authorization header, writing the file under its name in the folder it runs in." }, "powershell": { "type": "string", "description": "An Invoke-WebRequest command for Windows PowerShell, with -UseBasicParsing, which Windows PowerShell 5.1 needs: the same header and the same file." } }, "additionalProperties": false, "description": "The two commands that download the file, each sending a read-only grant as the bearer. Absent where `blocked`, or where no grant could be minted, which `detail` then says." }, "inline": { "type": "object", "required": [ "returned" ], "properties": { "returned": { "type": "boolean", "description": "Whether this answer carries the image as image content." }, "reason": { "type": "string", "description": "Where not returned: the image passes the bound, or the call did not arrive over MCP." } }, "additionalProperties": false, "description": "Present where the call passed `inline` true." }, "detail": { "type": "string", "description": "What happened and what to do next: the file's place and the commands' expiry, or the block's reason, with the month's use." } } } } ``` ## Shared contracts - [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy - [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/) - [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/) - [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes) - [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)