Image Tool

Image Description

Analyze images using AI vision models.

Endpoint

POST /v1/image/describe

Request

curl https://api.router9.com/v1/image/describe \
  -H "Authorization: Bearer sk-r9k-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://example.com/photo.jpg",
    "prompt": "What is in this image?"
  }'

Parameter	Type	Required	Description
`mediaUrl`	string	One of mediaUrl/mediaBase64	URL to image
`mediaBase64`	string	One of mediaUrl/mediaBase64	Base64-encoded image
`prompt`	string	No	Specific question about the image. Defaults to a general description
`model`	string	No	Override the default vision model (must be allowlisted)

Response

{
  "success": true,
  "tool": "image_describe",
  "result": {
    "text": "The image shows a modern office space with developers working at their desks, multiple monitors displaying code editors.",
    "model": "google/gemini-3.5-flash"
  }
}

Image Generation

Generate images from a text prompt.

Endpoint

POST /v1/image/generations

Request

curl https://api.router9.com/v1/image/generations \
  -H "Authorization: Bearer sk-r9k-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline at sunset, digital art",
    "aspect_ratio": "16:9",
    "output_format": "webp"
  }'

Parameter	Type	Required	Description
`prompt`	string	Yes	Description of the image to generate
`model`	string	No	Override the default image-generation model (must be allowlisted)
`n`	integer	No	Number of images. Capped per plan: 1 on Free, 4 on Pro, 10 on Max
`aspect_ratio`	string	No	`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
`output_format`	string	No	`png`, `jpeg`, `webp`, `svg`. Defaults to `webp`
`seed`	integer	No	Fixes the seed so the same inputs reproduce the same image
`quality`	string	No	`auto`, `low`, `medium`, `high`
`background`	string	No	`auto`, `transparent`, `opaque`. Transparency requires `png` or `webp`
`resolution`	string	No	`512`, `1K`, `2K`, `4K`. Capped per plan: 1K on Free, 2K on Pro, 4K on Max
`size`	string	No	Explicit pixels, e.g. `2048x2048`. Overrides `resolution` where supported
`output_compression`	integer	No	0–100, `webp` and `jpeg` only
`images`	string[]	No	Reference images to edit or draw from — see Editing

Parameter support varies by model. A value this endpoint accepts can still be refused upstream; that error is returned verbatim so you can see which model rejected what.

Response

{
  "created": 1714000000,
  "data": [
    {
      "b64_json": "UklGRiQAAABXRUJQ...",
      "media_type": "image/webp",
      "revised_prompt": "A futuristic city skyline at sunset, digital art"
    }
  ]
}

Images are returned as base64 bytes, never URLs. Use media_type to decode — do not assume PNG, since the default output format is WebP.

Image Editing

Pass images to edit existing images or guide generation with references. Up to four, as HTTP(S) URLs or data: URLs.

curl https://api.router9.com/v1/image/generations \
  -H "Authorization: Bearer sk-r9k-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "make this a watercolor painting",
    "images": ["https://example.com/photo.jpg"]
  }'

The gateway downloads referenced URLs itself rather than passing them upstream, so private and internal addresses are refused.

Over MCP this is a separate image_edit tool; the response shape is the same.

Image Skill calls consume credits from your plan's monthly credit allowance — the same allowance used for chat completions. There are no separate per-Skill quotas. Image models are priced per image or per megapixel, so n and resolution multiply what a single call costs. See Credits & Usage and Tool Usage & Credits.

On this page