DocsAPI ReferenceSDKsCookbookChangelog

For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://modelgates.ai/docs/_mcp/server.

Image Generation

Server tools are currently in beta. The API and behavior may change.

The modelgates:image_generation server tool enables any model to generate images from text prompts. When the model determines it needs to create an image, it calls the tool with a description. ModelGates executes the image generation and returns the result to the model.

How It Works

  1. You include { "type": "modelgates:image_generation" } in your tools array.
  2. Based on the user's request, the model decides whether image generation is needed and crafts a prompt.
  3. ModelGates generates the image using the configured model (defaults to openai/gpt-image-1).
  4. The generated image URL is returned to the model.
  5. The model incorporates the image into its response. It may generate multiple images in a single request if needed.

Quick Start

typescript
const response = await fetch('https://modelgates.ai/api/v1/chat/completions', {  method: 'POST',  headers: {    Authorization: 'Bearer {{API_KEY_REF}}',    'Content-Type': 'application/json',  },  body: JSON.stringify({    model: '{{MODEL}}',    messages: [      {        role: 'user',        content: 'Create an image of a futuristic city at sunset'      }    ],    tools: [      { type: 'modelgates:image_generation' }    ]  }),}); const data = await response.json();console.log(data.choices[0].message.content);
python
import requests response = requests.post(  "https://modelgates.ai/api/v1/chat/completions",  headers={    "Authorization": f"Bearer {{API_KEY_REF}}",    "Content-Type": "application/json",  },  json={    "model": "{{MODEL}}",    "messages": [      {        "role": "user",        "content": "Create an image of a futuristic city at sunset"      }    ],    "tools": [      {"type": "modelgates:image_generation"}    ]  }) data = response.json()print(data["choices"][0]["message"]["content"])
bash
curl https://modelgates.ai/api/v1/chat/completions \  -H "Authorization: Bearer {}" \  -H "Content-Type: application/json" \  -d '{    "model": "{{MODEL}}",    "messages": [      {        "role": "user",        "content": "Create an image of a futuristic city at sunset"      }    ],    "tools": [      {"type": "modelgates:image_generation"}    ]  }'

Configuration

The image generation tool accepts optional parameters to customize the output:

json
{  "type": "modelgates:image_generation",  "parameters": {    "model": "openai/gpt-image-1",    "quality": "high",    "aspect_ratio": "16:9",    "size": "1024x1024",    "background": "transparent",    "output_format": "png"  }}
ParameterTypeDefaultDescription
modelstringopenai/gpt-image-1Which image generation model to use
qualitystring—Image quality level (model-dependent, e.g. "low", "medium", "high")
sizestring—Image dimensions (e.g. "1024x1024", "512x512")
aspect_ratiostring—Aspect ratio (e.g. "16:9", "1:1", "4:3")
backgroundstring—Background style (e.g. "transparent", "opaque")
output_formatstring—Output format (e.g. "png", "jpeg", "webp")
output_compressionnumber—Compression level (0-100) for lossy formats
moderationstring—Content moderation level (e.g. "auto", "low")

All parameters except model are passed directly to the underlying image generation API. Available options depend on the specific model being used.

Response

When the model calls the image generation tool, it receives a response like:

json
{  "status": "ok",  "imageUrl": "https://..."}

If generation fails, the response includes an error:

json
{  "status": "error",  "error": "Generation failed due to content policy"}

Works with the Responses API

The image generation server tool also works with the Responses API:

typescript
const response = await fetch('https://modelgates.ai/api/v1/responses', {  method: 'POST',  headers: {    Authorization: 'Bearer {{API_KEY_REF}}',    'Content-Type': 'application/json',  },  body: JSON.stringify({    model: '{{MODEL}}',    input: 'Generate an image of a mountain landscape',    tools: [      {        type: 'modelgates:image_generation',        parameters: { quality: 'high' }      }    ]  }),}); const data = await response.json();console.log(data);
python
import requests response = requests.post(  "https://modelgates.ai/api/v1/responses",  headers={    "Authorization": f"Bearer {{API_KEY_REF}}",    "Content-Type": "application/json",  },  json={    "model": "{{MODEL}}",    "input": "Generate an image of a mountain landscape",    "tools": [      {        "type": "modelgates:image_generation",        "parameters": {"quality": "high"}      }    ]  }) data = response.json()print(data)

Pricing

Image generation pricing depends on the underlying model used:

  • openai/gpt-image-1: See OpenAI pricing
  • Other models: See the model's pricing page on ModelGates

The cost is in addition to standard LLM token costs for processing the request and response.

Next Steps