generate_image #
Generated automatically from the published 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.
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-<application id>. The application needs no deployed code. 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 #
{
"name": "generate_image",
"resource": "account",
"tier": "reversible",
"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-<application id>`, 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 #
{
"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-<application id>`. The application needs no deployed code. 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"] |
| / |
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 |
| / |
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)$ |
| / |
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 |
| / |
The image's size class; absent, 1K.Type: string Allowed values: ["1K","2K"] |
| / |
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"] |
| / |
Required value: 1 |
| / |
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}$ |
| / |
The application whose storage received the image. Type: string |
| / |
The model the platform called. Type: string |
| / |
The size class the call asked for. Type: string |
| / |
The account's images counted this UTC month, this call among them. Type: integer |
| / |
The account's images per UTC month. Type: integer |
| / |
The first instant of the next UTC month, as an ISO 8601 instant. Type: string |
| / |
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 |
| / |
With blocked: the provider's reason, in its own words.Type: string |
| / |
The partition the file is in. Absent where blocked.Type: string |
| / |
The file's storage area, images-<application id>. Absent where blocked.Type: string |
| / |
The file's name, which the platform chose. Absent where blocked.Type: string |
| / |
The file's type. Absent where blocked.Type: string |
| / |
The file's size. Absent where blocked.Type: integer |
| / |
The file's whole address on the platform's public origin, each segment of its name escaped. Absent where blocked.Type: string |
| / |
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 |
| / |
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 |
| / |
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 |
| / |
An Invoke-WebRequest command for Windows PowerShell, with -UseBasicParsing, which Windows PowerShell 5.1 needs: the same header and the same file. Type: string |
| / |
Present where the call passed inline true.Type: object Required fields: ["returned"] Additional properties: false |
| / |
Whether this answer carries the image as image content. Type: boolean |
| / |
Where not returned: the image passes the bound, or the call did not arrive over MCP. Type: string |
| / |
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 #
{
"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-<application id>`. 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: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md