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

# Image

> Create and edit images

## Overview

Use the Image MCP server from your ATXP-powered agent to create images based on a prompt.

## Example prompts

* "Create an image of a cat riding a horse. Use a realistic style."
* "Create a coloring page of a child and a puppy."

## Tools

<AccordionGroup>
  <Accordion title="image_create_image">
    Takes in a prompt, optional model, optional aspect ratio, and optional reference images. The output will be a URL to an image generated from the prompt. The image will be stored in the cloud and will expire in 180 days.

    ### Arguments

    Accepts a JSON object with the following properties:

    <ParamField body="prompt" type="string" required>
      The natural-language prompt to use to generate the image.
    </ParamField>

    <ParamField body="model" type="string" optional>
      Optional model to use for image generation. If not specified, uses the default model from environment variables.

      **OpenAI models:** `gpt-4o`, `gpt-4o-mini`, `gpt-image-1`, `dall-e-3`

      **Gemini models:** `imagen-4.0-generate-001`, `imagen-4.0-ultra-generate-001`, `imagen-4.0-fast-generate-001`, `imagen-3.0-generate-002`, `gemini-3-pro-image-preview`
    </ParamField>

    <ParamField body="aspectRatio" type="string" optional>
      Optional aspect ratio for the generated image. Defaults to `1:1` if not specified.

      **OpenAI supported ratios:** `1:1` (square), `16:9` (landscape), `9:16` (portrait)

      **Gemini supported ratios:** `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
    </ParamField>

    <ParamField body="referenceImages" type="array" optional>
      Optional array of reference images to incorporate into the generation. Images will be fetched from the provided URLs.

      <Expandable title="referenceImages properties">
        <ParamField body="url" type="string" required>
          URL of the reference image.
        </ParamField>

        <ParamField body="description" type="string" optional>
          Optional description of how to use this image (for example, "use as logo", "apply this style").
        </ParamField>
      </Expandable>
    </ParamField>

    ### Response

    Returns a JSON object with the following properties:

    <ResponseField name="status" type="string">
      The status of the image generation operation. Returns "success" when the image is generated successfully.
    </ResponseField>

    <ResponseField name="url" type="string">
      The URL that the image is accessible at for 1 day.
    </ResponseField>
  </Accordion>

  <Accordion title="image_create_image_async">
    Takes in a prompt, optional model, optional aspect ratio, and optional reference images, then starts asynchronous image generation. Returns a task ID that can be used to check status and retrieve the result. The image will be stored in the cloud and will expire in 180 days.

    ### Arguments

    Accepts a JSON object with the following properties:

    <ParamField body="prompt" type="string" required>
      The natural-language prompt to use to generate the image.
    </ParamField>

    <ParamField body="model" type="string" optional>
      Optional model to use for image generation. If not specified, uses the default model from environment variables.

      **OpenAI models:** `gpt-4o`, `gpt-4o-mini`, `gpt-image-1`, `dall-e-3`

      **Gemini models:** `imagen-4.0-generate-001`, `imagen-4.0-ultra-generate-001`, `imagen-4.0-fast-generate-001`, `imagen-3.0-generate-002`, `gemini-3-pro-image-preview`
    </ParamField>

    <ParamField body="aspectRatio" type="string" optional>
      Optional aspect ratio for the generated image. Defaults to `1:1` if not specified.

      **OpenAI supported ratios:** `1:1` (square), `16:9` (landscape), `9:16` (portrait)

      **Gemini supported ratios:** `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
    </ParamField>

    <ParamField body="referenceImages" type="array" optional>
      Optional array of reference images to incorporate into the generation. Images will be fetched from the provided URLs.

      <Expandable title="referenceImages properties">
        <ParamField body="url" type="string" required>
          URL of the reference image.
        </ParamField>

        <ParamField body="description" type="string" optional>
          Optional description of how to use this image (for example, "use as logo", "apply this style").
        </ParamField>
      </Expandable>
    </ParamField>

    ### Response

    Returns a JSON object with the following properties:

    <ResponseField name="taskId" type="string">
      A unique task identifier that can be used with `image_get_image_async` to check the status and retrieve the result.
    </ResponseField>
  </Accordion>

  <Accordion title="image_get_image_async">
    Retrieves the status and result of an asynchronous image generation task using the task ID. Tasks expire after 12 hours.

    ### Arguments

    Accepts a JSON object with the following properties:

    <ParamField body="taskId" type="string" required>
      The task ID returned from `image_create_image_async`.
    </ParamField>

    ### Response

    Returns a JSON object with the following properties:

    <ResponseField name="status" type="string">
      The current status of the task. Can be "pending", "processing", "completed", or "failed".
    </ResponseField>

    <ResponseField name="url" type="string">
      The URL that the image is accessible at for 180 days. Only present when status is "completed".
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Usage

<Steps>
  <Step title="Define the Image service">
    Create a reusable service configuration that points to the MCP server and standardizes how you pass arguments and read results. This lets your agent easily interact with the Image tools in a consistent manner.

    ```typescript theme={null}
    const imageService = {
        mcpServer: 'https://image.mcp.atxp.ai/',
        createImageToolName: 'image_create_image',
        createImageAsyncToolName: 'image_create_image_async',
        getImageAsyncToolName: 'image_get_image_async',
        description: 'ATXP Image MCP server',
        getArguments: (
          prompt: string,
          options?: {
            model?: string;
            aspectRatio?: string;
            referenceImages?: Array<{ url: string; description?: string }>;
          }
        ) => ({
          prompt,
          ...(options?.model && { model: options.model }),
          ...(options?.aspectRatio && { aspectRatio: options.aspectRatio }),
          ...(options?.referenceImages && { referenceImages: options.referenceImages })
        }),
        getResult: (result: any) => {
          const jsonResult = result.content[0].text;
          const parsed = JSON.parse(jsonResult);
          return { status: parsed.status, url: parsed.url };
        },
        getAsyncCreateResult: (result: any) => {
          const jsonResult = result.content[0].text;
          const parsed = JSON.parse(jsonResult);
          return { taskId: parsed.taskId };
        },
        getAsyncStatusResult: (result: any) => {
          const jsonResult = result.content[0].text;
          const parsed = JSON.parse(jsonResult);
          return { status: parsed.status, url: parsed.url };
        }
      };
    ```
  </Step>

  <Step title="Create an ATXP client">
    <Tabs>
      <Tab title="Using an ATXP account">
        Create a client using an <a href="/developers/build-agents/create-account" target="_blank">ATXP account</a> by importing the ATXP client SDK and other dependencies.

        ```typescript theme={null}
        // Import the ATXP client SDK
        import { atxpClient, ATXPAccount } from '@atxp/client';

        // Read the ATXP account details from environment variables
        const atxpConnectionString = process.env.ATXP_CONNECTION;

        // Create a client using the `atxpClient` function
        const client = await atxpClient({
          mcpServer: imageService.mcpServer,
          account: new ATXPAccount(atxpConnectionString),
        });
        ```
      </Tab>

      <Tab title="Using a Base account">
        Create a client using a Base account by importing the ATXP client SDK and other dependencies.

        ```typescript theme={null}
        // Import the ATXP client SDK and Base account
        import { atxpClient } from '@atxp/client';
        import { BaseAccount } from '@atxp/base';

        // Read the Base account details from the environment variables
        const baseRpcUrl = process.env.BASE_RPC_URL;
        const basePrivateKey = process.env.BASE_PRIVATE_KEY;

        // Create a client using the `atxpClient` function
        const client = await atxpClient({
          mcpServer: imageService.mcpServer,
          account: new BaseAccount(baseRpcUrl, basePrivateKey),
        });
        ```
      </Tab>

      <Tab title="Using a Solana account">
        Create a client using a Solana account by importing the ATXP client SDK and other dependencies.

        ```typescript theme={null}
        // Import the ATXP client SDK and Solana account
        import { atxpClient } from '@atxp/client';
        import { SolanaAccount } from '@atxp/solana';

        // Read the Solana account details from the environment variables
        const solanaRpcUrl = process.env.SOLANA_RPC_URL;
        const solanaPrivateKey = process.env.SOLANA_PRIVATE_KEY;

        // Create a client using the `atxpClient` function
        const client = await atxpClient({
          mcpServer: imageService.mcpServer,
          account: new SolanaAccount(solanaRpcUrl, solanaPrivateKey),
        });
        ```
      </Tab>

      <Tab title="Using a Worldchain account">
        Create a client using a Worldchain account with MiniKit integration.

        ```typescript theme={null}
        // Import the ATXP client SDK and Worldchain account creator
        import { atxpClient } from '@atxp/client';
        import { createMiniKitWorldchainAccount } from '@atxp/worldchain';
        import { MiniKit } from '@worldcoin/minikit-js';

        // Create a Worldchain account using MiniKit
        const account = await createMiniKitWorldchainAccount({
          walletAddress: '0x1234...', // User's wallet address
          miniKit: MiniKit
        });

        // Create a client using the `atxpClient` function
        const client = await atxpClient({
          mcpServer: imageService.mcpServer,
          account,
        });
        ```
      </Tab>

      <Tab title="Using a Polygon account">
        **Browser applications:**

        ```typescript theme={null}
        // Import the ATXP client SDK and Polygon browser account
        import { atxpClient } from '@atxp/client';
        import { PolygonBrowserAccount } from '@atxp/polygon';

        // Initialize the Polygon browser account with wallet provider
        const account = await PolygonBrowserAccount.initialize({
          provider: window.ethereum, // or any EIP-1193 provider
          walletAddress: '0x1234...', // User's wallet address
        });

        // Create a client using the `atxpClient` function
        const client = await atxpClient({
          mcpServer: imageService.mcpServer,
          account,
        });
        ```

        **Server/CLI applications:**

        ```typescript theme={null}
        // Import the ATXP client SDK and Polygon server account
        import { atxpClient } from '@atxp/client';
        import { PolygonServerAccount } from '@atxp/polygon';

        // Read the Polygon account details from the environment variables
        const polygonRpcUrl = process.env.POLYGON_RPC_URL;
        const polygonPrivateKey = process.env.POLYGON_PRIVATE_KEY;

        // Create a Polygon server account
        const account = new PolygonServerAccount(
          polygonRpcUrl,
          polygonPrivateKey,
          137 // Chain ID: 137 = Polygon mainnet, 80002 = Amoy testnet
        );

        // Create a client using the `atxpClient` function
        const client = await atxpClient({
          mcpServer: imageService.mcpServer,
          account,
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Use the Image service in your agent">
    <Tabs>
      <Tab title="Synchronous Generation">
        Call the Image tool by passing your natural-language instruction as the argument the `getArguments` method.

        Read the response using the `getResult` method.

        ```typescript theme={null}
        const prompt = "Create an image of a cat riding a horse. Use a realistic style.";

        try {
          const result = await client.callTool({
              name: imageService.createImageToolName,
              arguments: imageService.getArguments(prompt),
          });
          const { status, url } = imageService.getResult(result);
          console.log('Status:', status);
          console.log('URL:', url);
        } catch (error) {
          console.error(`Error with ${imageService.description}:`, error);
          process.exit(1);
        }
        ```

        <Check>
          You should see the result of the image creation printed in your console.
        </Check>

        **Using model and aspect ratio:**

        ```typescript theme={null}
        const prompt = "A panoramic landscape with mountains";

        try {
          const result = await client.callTool({
              name: imageService.createImageToolName,
              arguments: imageService.getArguments(prompt, {
                model: 'gpt-4o',
                aspectRatio: '16:9'
              }),
          });
          const { status, url } = imageService.getResult(result);
          console.log('Status:', status);
          console.log('URL:', url);
        } catch (error) {
          console.error(`Error with ${imageService.description}:`, error);
          process.exit(1);
        }
        ```

        **Using reference images:**

        ```typescript theme={null}
        const prompt = "Create a product photo with this logo";

        try {
          const result = await client.callTool({
              name: imageService.createImageToolName,
              arguments: imageService.getArguments(prompt, {
                referenceImages: [
                  {
                    url: 'https://example.com/logo.png',
                    description: 'use as logo in corner'
                  }
                ]
              }),
          });
          const { status, url } = imageService.getResult(result);
          console.log('Status:', status);
          console.log('URL:', url);
        } catch (error) {
          console.error(`Error with ${imageService.description}:`, error);
          process.exit(1);
        }
        ```
      </Tab>

      <Tab title="Asynchronous Generation">
        For longer image generation tasks, use the async tools to avoid blocking your application. Start the generation and poll for completion.

        ```typescript theme={null}
        const prompt = "Create an image of a cat riding a horse. Use a realistic style.";

        try {
          // Start async image generation
          const asyncResult = await client.callTool({
              name: imageService.createImageAsyncToolName,
              arguments: imageService.getArguments(prompt),
          });
          const { taskId } = imageService.getAsyncCreateResult(asyncResult);
          console.log('Task started with ID:', taskId);

          // Poll for completion
          let completed = false;
          while (!completed) {
            await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
            
            const statusResult = await client.callTool({
                name: imageService.getImageAsyncToolName,
                arguments: { taskId },
            });
            const { status, url } = imageService.getAsyncStatusResult(statusResult);
            
            console.log('Status:', status);
            
            if (status === 'completed') {
              console.log('URL:', url);
              completed = true;
            } else if (status === 'failed') {
              console.error('Image generation failed');
              completed = true;
            }
          }
        } catch (error) {
          console.error(`Error with ${imageService.description}:`, error);
          process.exit(1);
        }
        ```

        <Check>
          You should see the task ID printed first, followed by status updates, and finally the image URL when generation completes.
        </Check>
      </Tab>
    </Tabs>
  </Step>
</Steps>