{ "openapi": "3.0.3", "info": { "title": "Mafdet AI API", "version": "1.0.0", "description": "The Mafdet AI public API is OpenAI-compatible. Point any OpenAI SDK at the base URL below and authenticate with a Mafdet AI API key. The stable major version is v1 (part of the base URL path).\n\nCovers the publicly supported surfaces: Chat, Embeddings, Speech (Preview) and Models. Live/Realtime is a console-only invite-only beta and is deliberately not specified here; internal and admin endpoints are not part of the public API.", "x-api-version": "v1" }, "servers": [ { "url": "https://api.mafdet.ai/v1", "description": "Mafdet AI OpenAI-compatible endpoint (v1)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Chat", "description": "Chat completions" }, { "name": "Models", "description": "Model discovery" } ], "paths": { "/chat/completions": { "post": { "tags": ["Chat"], "operationId": "createChatCompletion", "summary": "Create a chat completion", "description": "OpenAI-compatible chat completion. Set \"stream\": true to receive server-sent events.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } }, "responses": { "200": { "description": "A chat completion (or an SSE stream when stream=true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/models": { "get": { "tags": ["Models"], "operationId": "listModels", "summary": "List available models", "description": "Returns the models your API key is allowed to call.", "responses": { "200": { "description": "The list of available models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/embeddings": { "post": { "tags": ["Embeddings"], "operationId": "createEmbedding", "summary": "Create embeddings", "description": "Turns text, images or video into vectors. `gemini-embedding-2` takes text; `multimodal-embedding-1` takes images (as `data:image/...;base64` data URIs) or one video (as `{\"video\":{\"bytesBase64Encoded\":\"...\"}}`, max 6s / 300KB). Billed per input token, per image, or per second depending on the model.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" } } } }, "responses": { "200": { "description": "The generated vectors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/audio/speech": { "post": { "tags": ["Speech"], "operationId": "createSpeech", "summary": "Create speech (Preview)", "description": "Synthesises speech with the Gemini TTS models. Returns the audio bytes (24 kHz mono 16-bit), not JSON. Preview surface. Billed on text input tokens plus audio output tokens.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechRequest" } } } }, "responses": { "200": { "description": "The audio file.", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Mafdet AI API key, sent as `Authorization: Bearer sk-mafdet-...`." } }, "responses": { "Error": { "description": "An error response. The body carries an error object with a machine-readable code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ChatCompletionRequest": { "type": "object", "required": ["model", "messages"], "properties": { "model": { "type": "string", "description": "The model id to call, e.g. \"gemini-3-flash\".", "example": "gemini-3-flash" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "max_tokens": { "type": "integer", "description": "Maximum tokens to generate.", "minimum": 1 }, "temperature": { "type": "number", "description": "Sampling temperature (0–2).", "minimum": 0, "maximum": 2 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean", "default": false, "description": "When true, tokens are streamed as server-sent events." } } }, "Message": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["system", "user", "assistant"] }, "content": { "type": "string" } } }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/Choice" } }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "Choice": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "$ref": "#/components/schemas/Message" }, "finish_reason": { "type": "string", "example": "stop" } } }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "Model": { "type": "object", "properties": { "id": { "type": "string", "example": "gemini-3-flash" }, "object": { "type": "string", "example": "model" }, "owned_by": { "type": "string", "example": "mafdet" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable error code (see the Errors & Troubleshooting page)." } } } } }, "EmbeddingRequest": { "type": "object", "required": ["model", "input"], "properties": { "model": { "type": "string", "example": "gemini-embedding-2" }, "input": { "description": "A string, an array of strings (max 100), an array of image data URIs (max 8), or one native video object.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object" } } ] }, "dimensions": { "type": "integer", "enum": [768, 1536, 3072], "default": 3072, "description": "Text embeddings only." } } }, "EmbeddingResponse": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "embedding" }, "index": { "type": "integer" }, "embedding": { "type": "array", "items": { "type": "number" } } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "SpeechRequest": { "type": "object", "required": ["model", "input", "voice"], "properties": { "model": { "type": "string", "enum": ["gemini-2.5-flash-tts", "gemini-2.5-pro-tts"] }, "input": { "type": "string", "maxLength": 5000 }, "voice": { "type": "string", "enum": ["Kore", "Puck", "Charon", "Fenrir", "Aoede"], "description": "Gemini voices only; OpenAI voice names are rejected." }, "response_format": { "type": "string", "enum": ["wav", "pcm"], "default": "wav" } } } } } }