Image

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

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:

prompt

string

required

The natural-language prompt to use to generate the image.

model

string

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-3Gemini 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

aspectRatio

string

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

referenceImages

array

Optional array of reference images to incorporate into the generation. Images will be fetched from the provided URLs.

Show referenceImages properties

url

string

required

URL of the reference image.

description

string

Optional description of how to use this image (for example, “use as logo”, “apply this style”).

Response

Returns a JSON object with the following properties:

status

string

The status of the image generation operation. Returns “success” when the image is generated successfully.

url

string

The URL that the image is accessible at for 1 day.

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:

prompt

string

required

The natural-language prompt to use to generate the image.

model

string

aspectRatio

string

referenceImages

array

Optional array of reference images to incorporate into the generation. Images will be fetched from the provided URLs.

Show referenceImages properties

url

string

required

URL of the reference image.

description

string

Optional description of how to use this image (for example, “use as logo”, “apply this style”).

Response

Returns a JSON object with the following properties:

taskId

string

A unique task identifier that can be used with image_get_image_async to check the status and retrieve the result.

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:

taskId

string

required

The task ID returned from image_create_image_async.

Response

Returns a JSON object with the following properties:

status

string

The current status of the task. Can be “pending”, “processing”, “completed”, or “failed”.

url

string

The URL that the image is accessible at for 180 days. Only present when status is “completed”.

Usage

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.

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 };
    }
  };

Create an ATXP client

Using an ATXP account
Using a Base account
Using a Solana account
Using a Worldchain account
Using a Polygon account

Create a client using an ATXP account by importing the ATXP client SDK and other dependencies.

// 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),
});

Create a client using a Base account by importing the ATXP client SDK and other dependencies.

// 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),
});

Create a client using a Solana account by importing the ATXP client SDK and other dependencies.

// 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),
});

Create a client using a Worldchain account with MiniKit integration.

// 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,
});

Browser applications:

// 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:

// 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,
});

Use the Image service in your agent

Synchronous Generation
Asynchronous Generation

Call the Image tool by passing your natural-language instruction as the argument the getArguments method.Read the response using the getResult method.

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);
}

You should see the result of the image creation printed in your console.

Using model and aspect ratio:

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:

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);
}

For longer image generation tasks, use the async tools to avoid blocking your application. Start the generation and poll for completion.

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);
}

You should see the task ID printed first, followed by status updates, and finally the image URL when generation completes.

Overview

Web and Data

Storage

Creative

Development

Other

Overview

Example prompts

Tools

Arguments

Response

Arguments

Response

Arguments

Response

Usage

Overview

Web and Data

Storage

Creative

Development

Other

Documentation Index

​Overview

​Example prompts

​Tools

​Arguments

​Response

​Arguments

​Response

​Arguments

​Response

​Usage

Overview

Example prompts

Tools

Arguments

Response

Arguments

Response

Arguments

Response

Usage