{
  "openapi": "3.1.0",
  "info": {
    "title": "theaimart AIx API",
    "description": "Unified AI inference API with OpenAI-compatible and Messages-compatible surfaces for chat, embeddings, images, audio and a live model catalog.",
    "version": "1.1.0",
    "contact": { "name": "theaimart AIx", "url": "https://aix.theaimart.co" }
  },
  "servers": [
    { "url": "https://api.aix.theaimart.co/v1", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }, { "apiKeyAuth": [] }],
  "tags": [
    { "name": "Chat" },
    { "name": "Messages" },
    { "name": "Embeddings" },
    { "name": "Images" },
    { "name": "Audio" },
    { "name": "Models" }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "tags": ["Chat"],
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Replays a completed non-streaming chat request or rejects a duplicate streaming request. Retained for 24 hours.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion, or an SSE stream of chat.completion.chunk when stream=true.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletion" }
              },
              "text/event-stream": {
                "schema": { "type": "string" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/messages": {
      "post": {
        "tags": ["Messages"],
        "operationId": "createMessage",
        "summary": "Create a Messages-compatible completion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MessagesRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message response, or a Messages-compatible SSE event stream when stream=true.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MessageResponse" }
              },
              "text/event-stream": {
                "schema": { "type": "string" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/MessagesError" },
          "402": { "$ref": "#/components/responses/MessagesError" },
          "403": { "$ref": "#/components/responses/MessagesError" },
          "429": { "$ref": "#/components/responses/MessagesError" },
          "500": { "$ref": "#/components/responses/MessagesError" },
          "503": { "$ref": "#/components/responses/MessagesError" }
        }
      }
    },
    "/embeddings": {
      "post": {
        "tags": ["Embeddings"],
        "operationId": "createEmbedding",
        "summary": "Create embeddings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmbeddingRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding vectors.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EmbeddingList" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/images/generations": {
      "post": {
        "tags": ["Images"],
        "operationId": "createImage",
        "summary": "Generate images",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ImageRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated images.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImageList" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/audio/speech": {
      "post": {
        "tags": ["Audio"],
        "operationId": "createSpeech",
        "summary": "Text to speech",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SpeechRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Raw audio bytes.",
            "content": {
              "audio/mpeg": { "schema": { "type": "string", "format": "binary" } },
              "audio/wav": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/audio/transcriptions": {
      "post": {
        "tags": ["Audio"],
        "operationId": "createTranscription",
        "summary": "Transcribe audio",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "model": { "type": "string", "default": "openai/whisper-large-v3-turbo" },
                  "prompt": { "type": "string", "description": "Optional spelling or continuation context." },
                  "response_format": { "type": "string", "enum": ["json", "text", "verbose_json"], "default": "json" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transcription.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "text": { "type": "string" } } }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/models": {
      "get": {
        "tags": ["Models"],
        "operationId": "listModels",
        "summary": "List available models",
        "security": [],
        "responses": {
          "200": {
            "description": "Live callable model catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ModelList" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as a bearer token, e.g. `Authorization: Bearer tam_...`."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative API key header for direct HTTP integrations."
      }
    },
    "responses": {
      "Error": {
        "description": "OpenAI-compatible error envelope.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "MessagesError": {
        "description": "Messages-compatible error envelope.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/MessagesErrorResponse" }
          }
        }
      }
    },
    "schemas": {
      "ChatMessage": {
        "type": "object",
        "required": ["role"],
        "properties": {
          "role": { "type": "string", "enum": ["system", "user", "assistant", "tool"] },
          "content": {
            "description": "String, or a multimodal content array (text + image_url parts).",
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "object" } }
            ]
          },
          "name": { "type": "string" },
          "tool_calls": { "type": "array", "items": { "type": "object" } },
          "tool_call_id": { "type": "string" }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string", "example": "deepseek-ai/DeepSeek-V3.2" },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } },
          "stream": { "type": "boolean", "default": false },
          "temperature": { "type": "number", "default": 0.7, "minimum": 0, "maximum": 2 },
          "max_tokens": { "type": "integer", "default": 256 },
          "top_p": { "type": "number", "default": 1.0 },
          "stop": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
          "n": { "type": "integer", "default": 1 },
          "presence_penalty": { "type": "number", "default": 0 },
          "frequency_penalty": { "type": "number", "default": 0 },
          "tools": { "type": "array", "items": { "type": "object" } },
          "tool_choice": { "oneOf": [{ "type": "string" }, { "type": "object" }] },
          "response_format": { "type": "object" }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "example": "chat.completion" },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": { "$ref": "#/components/schemas/ChatMessage" },
                "finish_reason": { "type": "string" }
              }
            }
          },
          "usage": { "$ref": "#/components/schemas/Usage" }
        }
      },
      "MessagesRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string", "example": "anthropic/claude-sonnet-4-6" },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["role", "content"],
              "properties": {
                "role": { "type": "string", "enum": ["user", "assistant"] },
                "content": {
                  "oneOf": [
                    { "type": "string" },
                    { "type": "array", "items": { "type": "object" } }
                  ]
                }
              }
            }
          },
          "system": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "object" } }
            ]
          },
          "max_tokens": { "type": "integer", "default": 256 },
          "temperature": { "type": "number", "default": 0.7 },
          "top_p": { "type": "number", "default": 1.0 },
          "stop_sequences": { "type": "array", "items": { "type": "string" } },
          "stream": { "type": "boolean", "default": false },
          "tools": { "type": "array", "items": { "type": "object" } },
          "tool_choice": { "type": "object" }
        }
      },
      "MessageResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "example": "message" },
          "role": { "type": "string", "example": "assistant" },
          "model": { "type": "string" },
          "content": { "type": "array", "items": { "type": "object" } },
          "stop_reason": { "type": ["string", "null"] },
          "stop_sequence": { "type": ["string", "null"] },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": { "type": "integer" },
              "output_tokens": { "type": "integer" }
            }
          }
        }
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": ["input"],
        "properties": {
          "model": { "type": "string", "default": "BAAI/bge-large-en-v1.5" },
          "input": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
          "encoding_format": { "type": "string", "enum": ["float", "base64"], "default": "float" }
        }
      },
      "EmbeddingList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "list" },
          "model": { "type": "string" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "object": { "type": "string", "example": "embedding" },
                "index": { "type": "integer" },
                "embedding": { "type": "array", "items": { "type": "number" } }
              }
            }
          },
          "usage": { "$ref": "#/components/schemas/Usage" }
        }
      },
      "ImageRequest": {
        "type": "object",
        "required": ["model", "prompt"],
        "properties": {
          "model": { "type": "string", "example": "black-forest-labs/FLUX-1.1-pro" },
          "prompt": { "type": "string" },
          "n": { "type": "integer", "default": 1, "minimum": 1, "maximum": 4 },
          "size": { "type": "string", "default": "1024x1024", "enum": ["512x512", "768x768", "1024x1024", "1024x768", "768x1024"] }
        }
      },
      "ImageList": {
        "type": "object",
        "properties": {
          "created": { "type": "integer" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "b64_json": { "type": "string" },
                "url": { "type": "string" }
              }
            }
          }
        }
      },
      "SpeechRequest": {
        "type": "object",
        "required": ["model", "input"],
        "properties": {
          "model": { "type": "string", "example": "hexgrad/Kokoro-82M" },
          "input": { "type": "string" },
          "voice": { "type": "string", "default": "af_bella" },
          "response_format": { "type": "string", "enum": ["mp3", "wav"], "default": "mp3" }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "list" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "object": { "type": "string", "example": "model" },
                "created": { "type": "integer" },
                "owned_by": { "type": "string", "example": "theaimart" },
                "type": { "type": "string", "enum": ["chat", "embeddings", "image", "tts", "audio"] }
              }
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": { "type": "integer" },
          "completion_tokens": { "type": "integer" },
          "total_tokens": { "type": "integer" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string" },
              "code": { "type": ["string", "null"] },
              "param": { "type": ["string", "null"] }
            }
          }
        }
      },
      "MessagesErrorResponse": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "example": "error" },
          "error": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "example": "invalid_request_error" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}