Skip to main content

​
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

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.

​
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.
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
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.

​
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.
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

1

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

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

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