Images (beta)

Overview

The images endpoint family provides text-to-image generation capabilities via MultiRoute. This functionality is currently beta and may change without notice as we refine the contract and underlying routing behavior.

Use this endpoint to:

Generate images from natural language prompts.
Experiment with different models and quality settings through a unified API.

Status

Beta / experimental
The images API is considered experimental. Fields, response formats, and supported models may evolve. Avoid hard-coding against this contract for long-lived production systems without version pinning and monitoring.

Endpoint

Method: POST
Path: /v1/images/generations
Base URL: https://api.multiroute.ai/v1

Full URL:

https://api.multiroute.ai/v1/images/generations

Authentication is required via the Authorization: Bearer <your-api-key> header.

Request body

The request body is JSON with at least a model and a prompt, plus optional generation parameters:

model (string, required): Image-capable model identifier (for example, "multiroute-image-latest").
prompt (string, required): Natural language description of the image you want.
n (integer, optional, default 1): Number of images to generate.
size (string, optional): Target resolution, such as "512x512", "1024x1024", or model-specific sizes.
response_format (string, optional): Output format. Common options:
- "url": Return URLs pointing to hosted images.
- "b64_json": Return base64-encoded image data.
user (string, optional): An opaque identifier for your end-user, for observability and abuse monitoring.

Example request body

{
  "model": "multiroute-image-latest",
  "prompt": "A minimalist illustration of a mountain range at sunrise in a flat vector style",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}

Response body

The endpoint returns a JSON object describing generated images:

created (integer): Unix timestamp (seconds).
data (array): List of generated images.
- Each entry may include:
  - url (string): URL to download or view the image (when response_format: "url").
  - b64_json (string): Base64-encoded image data (when response_format: "b64_json").
  - revised_prompt (string, optional): The prompt actually used by the underlying model after any rewriting or safety filtering.

Example response (`response_format: "url"`)

{
  "created": 1710000001,
  "data": [
    {
      "url": "https://cdn.multiroute.ai/images/img-abc123.png",
      "revised_prompt": "A minimalist vector illustration of mountains at sunrise."
    }
  ]
}

Examples

cURL

curl https://api.multiroute.ai/v1/images/generations \
  -H "Authorization: Bearer $MULTIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "multiroute-image-latest",
    "prompt": "An isometric illustration of a microservice architecture diagram",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

TypeScript / Node (fetch)

const apiKey = process.env.MULTIROUTE_API_KEY!;

async function generateImage() {
  const response = await fetch("https://api.multiroute.ai/v1/images/generations", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "multiroute-image-latest",
      prompt: "A multi-colored logo representing API routing and orchestration",
      n: 1,
      size: "512x512",
      response_format: "url",
    }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`Request failed: ${response.status} ${errorBody}`);
  }

  const data = await response.json();
  console.log("Image URL:", data.data[0]?.url);
}

generateImage().catch(console.error);

Python (`requests`)

import os
import requests

API_KEY = os.environ.get("MULTIROUTE_API_KEY")

def generate_image():
  url = "https://api.multiroute.ai/v1/images/generations"
  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
  }
  json_body = {
      "model": "multiroute-image-latest",
      "prompt": "A clean dashboard UI screenshot for monitoring API routing performance",
      "n": 1,
      "size": "1024x1024",
      "response_format": "url",
  }

  resp = requests.post(url, headers=headers, json=json_body, timeout=60)
  resp.raise_for_status()
  data = resp.json()
  print("Image URL:", data["data"][0]["url"])

if __name__ == "__main__":
  generate_image()

Best practices

Safety and content policy: Prompts may be filtered or rewritten to comply with safety and content guidelines. Use revised_prompt (when present) to understand how a request was transformed.
Storage: Download and store images in your own infrastructure if you need long-term retention. Hosted URLs may expire or be rotated.
Monitoring: Because this API is beta, monitor for changes in response shape and fields. When possible, validate responses and log unexpected structures.