Generate an image from your AI tool #

View this page as Markdown

Prompt:

Draw a logo for my recipe app and save it where I can get at it.

Also works:

  • "Make me a cover picture for the landing page."
  • "Draw three icons for the menu."

Use this page when you want one picture now, made by your AI tool in the conversation. If your deployed application should make pictures for its users, read Generate an image with AI instead.

What you need #

  • A Turn Zero account with an application. The application needs no code deployed, because the picture is only saved in its storage. Your AI tool can create one with create_application, which uses your account's one Free application if it's still free.
  • An AI tool signed in as you, or an account-wide token (Connect your AI coding tool). A token bounded to one application or by a grant can't call this, and neither can a device sign-in or an application's platform credential.
  • No provider account and no provider key.

Before your AI starts #

For the AI tool: Check the following before starting.

  • The application's identifier, from list_applications.
  • The month's use, from read_account on your own sign-in: image_generation gives used, cap, and resets_at. A token minted for a job does not receive that member. An authorized computer's token does.

Steps #

1. Generate the image #

Your AI tool calls generate_image with application and prompt. A prompt holds at most 8,000 characters. The prompt goes to the model's provider, and the platform keeps only a digest of it.

Two inputs are optional:

  • resolution is 1K, the default, or 2K. The platform uses one model, and you don't choose it.
  • environment is development or production, the partition that receives the file. Absent, the file goes to the environment the application's deploys go to.

An AI tool that can't run a shell command also passes inline: true.

2. Get the file #

When a picture is saved, the result gives its address and its name, which the platform chose. It normally includes two download commands, commands.curl and commands.powershell. Your AI tool runs the one for its shell. Each sends a read-only grant that works until expires_at, five minutes after the call. Treat a command as you would a password while it works.

If the grant cannot be created, the picture stays saved and counted. The result includes no download commands, and its detail says how else to read the file.

The address alone downloads nothing, because the file is private, so a browser can't open it. There is no link to share.

With inline: true over MCP, a saved picture also appears in the result if it is at most 256 KiB. A larger picture stays in the application's storage. Use a download command, where one is included, to fetch it; an AI tool with no shell needs another tool that can run one.

3. Keep or delete it #

The file stays in the area images-<application id> until you delete it, as any stored file. It counts in that application's stored data. A repeat call never replaces an earlier picture. Store files says how to read and delete stored files.

4. Know what counts #

During the introductory period, each account has 20 images per UTC month. Generating these pictures has no charge and uses none of an application's AI allowance.

An admitted call counts even if it produces no saved picture:

  • A provider's block, which answers blocked: true with the reason and writes no file.
  • image_generation_failed, including a call that passes 45 seconds, because the provider may have charged. A repeat spends another image.

A provider refusal before any picture normally gives the image back. If that fails, the call stays counted, and the refusal's detail says so.

Expected result #

The answer shows used one higher, and the downloaded file opens as a picture of about the size you asked for.

Refusals #

See the refusals reference for other platform errors.

Refusal Status Cause Remedy
application_required 400 The call named no application, or the account holds none. Pass an identifier from list_applications, or call create_application first.
environment_not_created 409 The application doesn't have the environment the call named. Name production, or call create_environment first.
usage_over_quota 429 The application is over its plan's stored data, so nothing was saved or counted. Delete stored files and wait for the next daily check, or call set_plan for a larger plan.
image_cap_reached 429 The account has generated its images this UTC month. Nothing was sent or counted. Wait for the instant resets_at gives, then repeat the request.
image_generation_busy 429 The platform is holding as many image calls as it allows at once. Nothing was counted. Repeat the request after a few seconds.
image_generation_failed 502 The call failed or passed 45 seconds, no image was saved, and it stays counted. Repeat it where the month's use allows. Where it keeps happening, quote the reference with submit_feedback.
image_generation_unavailable 503 The platform has no key for image generation or cannot make images right now. Its key could not be read, it has no current model price, the provider refused before any picture, or the platform's monthly limit was reached. Repeat the request later.