{
  "openapi": "3.1.0",
  "info": {
    "title": "Axe AI Multimodal API",
    "version": "1.0.0",
    "description": "Use Axe AI text, image, and video models through the public v1 API. Create a scoped API key at https://axeai.com/api and send it as a Bearer token."
  },
  "servers": [
    {
      "url": "https://axeai.com",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Models", "description": "Discover available Axe AI models and capabilities." },
    { "name": "Text", "description": "Create OpenAI-compatible chat completions." },
    { "name": "Images", "description": "Generate image assets." },
    { "name": "Videos", "description": "Submit and inspect asynchronous video jobs." },
    { "name": "Account", "description": "Inspect API credit usage." }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List models",
        "description": "Returns the current Axe AI model catalog. Filter the catalog by modality when an agent only needs text, image, or video models.",
        "tags": ["Models"],
        "parameters": [
          {
            "name": "modality",
            "in": "query",
            "required": false,
            "description": "Limit results to one model modality.",
            "schema": { "type": "string", "enum": ["text", "image", "video"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Current model catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ModelList" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion",
        "description": "Creates an OpenAI-compatible chat completion. Function definitions, tool choices, tool results, streaming, and parallel tool calls are supported.",
        "tags": ["Text"],
        "security": [{ "AxeApiKey": [] }],
        "x-axeai-required-scope": "chat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A completion object, or an SSE stream when stream is true.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/InsufficientCredits" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "operationId": "generateImage",
        "summary": "Generate an image",
        "description": "Generates an image and returns the saved Axe AI asset with its conversation thread identifier.",
        "tags": ["Images"],
        "security": [{ "AxeApiKey": [] }],
        "x-axeai-required-scope": "image",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated image asset.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" } }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/InsufficientCredits" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/videos/generations": {
      "post": {
        "operationId": "generateVideo",
        "summary": "Submit a video generation job",
        "description": "Queues text-to-video generation and returns the asynchronous job with its conversation thread identifier.",
        "tags": ["Videos"],
        "security": [{ "AxeApiKey": [] }],
        "x-axeai-required-scope": "video",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VideoGenerationRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Queued video job.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationResponse" } }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/InsufficientCredits" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/videos/jobs/{jobId}": {
      "get": {
        "operationId": "getVideoJob",
        "summary": "Get a video job",
        "description": "Returns the current job and its generated asset when the job has completed.",
        "tags": ["Videos"],
        "security": [{ "AxeApiKey": [] }],
        "x-axeai-required-scope": "video",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "Video job identifier returned by generateVideo.",
            "schema": { "type": "string", "minLength": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "Current video job and optional completed asset.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/VideoJobResponse" } }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/v1/account/usage": {
      "get": {
        "operationId": "getAccountUsage",
        "summary": "Get available credits",
        "description": "Returns the current Axe AI credit balance for the API key owner.",
        "tags": ["Account"],
        "security": [{ "AxeApiKey": [] }],
        "x-axeai-required-scope": "chat",
        "responses": {
          "200": {
            "description": "Current account credit balance.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsage" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AxeApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "axe_live_...",
        "description": "A scoped Axe AI API key created at https://axeai.com/api. Keys can grant chat, image, and video capabilities."
      }
    },
    "schemas": {
      "ModelList": {
        "type": "object",
        "required": ["object", "servedBy", "data"],
        "properties": {
          "object": { "type": "string", "const": "list" },
          "servedBy": { "type": "string", "const": "Axe AI" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }
        }
      },
      "Model": {
        "type": "object",
        "required": ["id", "name", "modality"],
        "properties": {
          "id": { "type": "string", "description": "Model identifier accepted by generation endpoints." },
          "name": { "type": "string" },
          "developer": { "type": "string" },
          "modality": { "type": "string", "enum": ["text", "image", "video"] },
          "agentCompatible": { "type": "boolean" },
          "offline": { "type": "boolean" },
          "capabilities": { "type": "object", "additionalProperties": true },
          "pricing": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "additionalProperties": false,
        "properties": {
          "model": { "type": "string", "minLength": 1, "maxLength": 160 },
          "messages": {
            "type": "array",
            "minItems": 1,
            "items": { "$ref": "#/components/schemas/ChatMessage" }
          },
          "tools": {
            "type": "array",
            "minItems": 1,
            "maxItems": 64,
            "items": { "$ref": "#/components/schemas/ToolDefinition" }
          },
          "tool_choice": {
            "oneOf": [
              { "type": "string", "enum": ["none", "auto", "required"] },
              { "$ref": "#/components/schemas/NamedToolChoice" }
            ]
          },
          "parallel_tool_calls": { "type": "boolean" },
          "stream": { "type": "boolean", "default": false },
          "max_tokens": { "type": "integer", "minimum": 1 }
        }
      },
      "ChatMessage": {
        "oneOf": [
          {
            "type": "object",
            "required": ["role", "content"],
            "additionalProperties": false,
            "properties": {
              "role": { "type": "string", "enum": ["system", "user"] },
              "content": { "type": "string" }
            }
          },
          {
            "type": "object",
            "required": ["role"],
            "additionalProperties": false,
            "properties": {
              "role": { "type": "string", "const": "assistant" },
              "content": { "type": ["string", "null"] },
              "tool_calls": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCall" } }
            }
          },
          {
            "type": "object",
            "required": ["role", "content", "tool_call_id"],
            "additionalProperties": false,
            "properties": {
              "role": { "type": "string", "const": "tool" },
              "content": { "type": "string" },
              "tool_call_id": { "type": "string" }
            }
          }
        ]
      },
      "ToolDefinition": {
        "type": "object",
        "required": ["type", "function"],
        "additionalProperties": false,
        "properties": {
          "type": { "type": "string", "const": "function" },
          "function": {
            "type": "object",
            "required": ["name", "parameters"],
            "additionalProperties": false,
            "properties": {
              "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
              "description": { "type": "string", "maxLength": 2000 },
              "parameters": { "type": "object", "additionalProperties": true }
            }
          }
        }
      },
      "ToolCall": {
        "type": "object",
        "required": ["id", "type", "function"],
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "const": "function" },
          "function": {
            "type": "object",
            "required": ["name", "arguments"],
            "properties": {
              "name": { "type": "string" },
              "arguments": { "type": "string", "description": "JSON-encoded function arguments." }
            }
          }
        }
      },
      "NamedToolChoice": {
        "type": "object",
        "required": ["type", "function"],
        "additionalProperties": false,
        "properties": {
          "type": { "type": "string", "const": "function" },
          "function": {
            "type": "object",
            "required": ["name"],
            "properties": { "name": { "type": "string" } }
          }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "required": ["id", "choices"],
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string" },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "usage": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "ImageGenerationRequest": {
        "type": "object",
        "required": ["prompt"],
        "additionalProperties": false,
        "properties": {
          "prompt": { "type": "string", "minLength": 3, "maxLength": 4000 },
          "model": { "type": "string", "minLength": 1, "maxLength": 160 },
          "threadId": { "type": "string", "format": "uuid" },
          "referenceImages": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "object",
              "required": ["url", "mediaType"],
              "additionalProperties": false,
              "properties": {
                "url": { "type": "string", "pattern": "^/api/files/file_[0-9a-fA-F]{32}$" },
                "mediaType": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"] },
                "filename": { "type": "string", "maxLength": 255 }
              }
            }
          }
        }
      },
      "VideoGenerationRequest": {
        "type": "object",
        "required": ["prompt"],
        "additionalProperties": false,
        "properties": {
          "prompt": { "type": "string", "minLength": 3, "maxLength": 4000 },
          "model": { "type": "string", "minLength": 1, "maxLength": 160 },
          "threadId": { "type": "string", "format": "uuid" }
        }
      },
      "Asset": {
        "type": ["object", "null"],
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "enum": ["image", "video"] },
          "prompt": { "type": "string" },
          "url": { "type": "string" },
          "provider": { "type": "string", "const": "Axe AI" },
          "model": { "type": "string" },
          "status": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": true
      },
      "VideoJob": {
        "type": ["object", "null"],
        "properties": {
          "id": { "type": "string" },
          "requestId": { "type": "string" },
          "prompt": { "type": "string" },
          "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] },
          "provider": { "type": "string", "const": "Axe AI" },
          "model": { "type": "string" },
          "assetId": { "type": "string" },
          "failureReason": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": true
      },
      "ImageGenerationResponse": {
        "type": "object",
        "required": ["asset", "threadId"],
        "properties": {
          "asset": { "$ref": "#/components/schemas/Asset" },
          "threadId": { "type": "string", "format": "uuid" }
        }
      },
      "VideoGenerationResponse": {
        "type": "object",
        "required": ["job", "threadId"],
        "properties": {
          "job": { "$ref": "#/components/schemas/VideoJob" },
          "threadId": { "type": "string", "format": "uuid" }
        }
      },
      "VideoJobResponse": {
        "type": "object",
        "required": ["job", "asset"],
        "properties": {
          "job": { "$ref": "#/components/schemas/VideoJob" },
          "asset": { "$ref": "#/components/schemas/Asset" }
        }
      },
      "AccountUsage": {
        "type": "object",
        "required": ["balance", "currency", "updatedAt"],
        "properties": {
          "balance": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "const": "credits" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "properties": {
                  "message": { "type": "string" },
                  "type": { "type": "string" },
                  "code": { "type": "string" }
                },
                "additionalProperties": true
              }
            ]
          },
          "message": { "type": "string" },
          "code": { "type": "string" }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "The request body or parameters are invalid.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "The API key is missing, invalid, expired, or lacks the required scope.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "InsufficientCredits": {
        "description": "The account does not have enough Axe AI credits for the request.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "The request rate limit was exceeded.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ServerError": {
        "description": "The request could not be completed.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}