{
  "openapi": "3.1.0",
  "info": {
    "title": "MetisRouter Public AI Gateway API",
    "version": "2026-06-05",
    "description": "Public OpenAPI summary for MetisRouter model discovery and AI model invocation routes. Use exact model IDs from /v1/models or https://www.metisrouter.com/docs/models."
  },
  "servers": [
    {
      "url": "https://api.metisrouter.com/v1",
      "description": "MetisRouter OpenAI-compatible API base URL"
    },
    {
      "url": "https://api.metisrouter.com",
      "description": "MetisRouter direct provider-compatible base URL"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/models": {
      "get": {
        "summary": "List published models",
        "description": "Returns model IDs and metadata available to the API key. Use the returned model IDs in request bodies.",
        "operationId": "listModels",
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          }
        }
      }
    },
    "/chat/completions": {
      "post": {
        "summary": "Create an OpenAI-compatible chat completion",
        "operationId": "createChatCompletion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion response or stream depending on request parameters"
          }
        }
      }
    },
    "/responses": {
      "post": {
        "summary": "Create a Responses-style request",
        "operationId": "createResponse",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponsesRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Responses-style model output"
          }
        }
      }
    },
    "/images/generations": {
      "post": {
        "summary": "Generate images",
        "operationId": "generateImages",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated image result"
          }
        }
      }
    },
    "/images/edits": {
      "post": {
        "summary": "Edit images where supported by the selected model",
        "operationId": "editImages",
        "responses": {
          "200": {
            "description": "Edited image result"
          }
        }
      }
    },
    "/videos": {
      "post": {
        "summary": "Create a video generation task where supported by the selected model",
        "operationId": "createVideo",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VideoRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Video task or generated video result depending on model behavior"
          }
        }
      }
    },
    "/audio/speech": {
      "post": {
        "summary": "Generate speech audio",
        "operationId": "createSpeech",
        "responses": {
          "200": {
            "description": "Generated audio",
            "content": {
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechRequest"
              }
            }
          }
        }
      }
    },
    "/audio/transcriptions": {
      "post": {
        "summary": "Transcribe audio",
        "operationId": "createTranscription",
        "responses": {
          "200": {
            "description": "Transcription result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTranscriptionResponse"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AudioTranscriptionRequest"
              }
            }
          }
        }
      }
    },
    "/audio/translations": {
      "post": {
        "summary": "Translate audio",
        "operationId": "createTranslation",
        "responses": {
          "200": {
            "description": "Translation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioTranscriptionResponse"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AudioTranslationRequest"
              }
            }
          }
        }
      }
    },
    "/embeddings": {
      "post": {
        "summary": "Create embeddings",
        "operationId": "createEmbedding",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding vectors"
          }
        }
      }
    },
    "/messages": {
      "post": {
        "summary": "Anthropic Direct-compatible messages route for supported models",
        "operationId": "createAnthropicMessage",
        "description": "Use only with models tagged Anthropic Direct in the MetisRouter model catalog.",
        "responses": {
          "200": {
            "description": "Anthropic-style message response"
          }
        }
      }
    },
    "/v1beta/models/{model}:generateContent": {
      "post": {
        "summary": "Gemini Direct-compatible generateContent route for supported models",
        "operationId": "generateGeminiContent",
        "description": "Use only with models tagged Gemini Direct in the MetisRouter model catalog.",
        "parameters": [
          {
            "name": "model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Gemini-style generation response"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ModelList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string"
          },
          "owned_by": {
            "type": "string"
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "stream": {
            "type": "boolean"
          },
          "max_tokens": {
            "type": "integer",
            "description": "Recommended for low-balance requests so maximum output cost can be reserved."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "ResponsesRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "input": {},
          "max_output_tokens": {
            "type": "integer"
          },
          "stream": {
            "type": "boolean"
          }
        }
      },
      "ImageGenerationRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "n": {
            "type": "integer"
          },
          "size": {
            "type": "string"
          },
          "quality": {
            "type": "string"
          }
        }
      },
      "VideoRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "seconds": {
            "description": "Output duration in seconds. Send a number such as 4; string values such as \"4\" are accepted for compatibility.",
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "duration": {
            "type": "number"
          },
          "size": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          }
        }
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "input": {}
        }
      },
      "SpeechRequest": {
        "type": "object",
        "required": [
          "model",
          "input",
          "voice"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "gpt-4o-mini-tts"
          },
          "input": {
            "type": "string",
            "description": "Text to convert to speech.",
            "maxLength": 4096
          },
          "voice": {
            "type": "string",
            "description": "Voice name supported by the selected speech model.",
            "example": "alloy"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "mp3",
              "opus",
              "aac",
              "flac",
              "wav",
              "pcm"
            ],
            "default": "mp3"
          },
          "speed": {
            "type": "number",
            "minimum": 0.25,
            "maximum": 4,
            "default": 1
          }
        }
      },
      "AudioTranscriptionRequest": {
        "type": "object",
        "required": [
          "file",
          "model"
        ],
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Audio file to transcribe."
          },
          "model": {
            "type": "string",
            "example": "gpt-4o-mini-transcribe"
          },
          "language": {
            "type": "string",
            "description": "Optional ISO-639-1 language code."
          },
          "prompt": {
            "type": "string"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "json",
              "text",
              "srt",
              "verbose_json",
              "vtt"
            ],
            "default": "json"
          },
          "temperature": {
            "type": "number"
          },
          "timestamp_granularities": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "word",
                "segment"
              ]
            }
          }
        }
      },
      "AudioTranslationRequest": {
        "type": "object",
        "required": [
          "file",
          "model"
        ],
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Audio file to translate."
          },
          "model": {
            "type": "string",
            "example": "whisper-1"
          },
          "prompt": {
            "type": "string"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "json",
              "text",
              "srt",
              "verbose_json",
              "vtt"
            ],
            "default": "json"
          },
          "temperature": {
            "type": "number"
          }
        }
      },
      "AudioTranscriptionResponse": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "usage": {
            "type": "object",
            "description": "Token or audio usage when returned by the selected model."
          }
        }
      }
    }
  }
}