{
  "openapi": "3.1.0",
  "info": {
    "title": "OneFreeAPI",
    "version": "1.0.0",
    "summary": "OpenAI-compatible gateway for Chinese LLMs (Doubao, DeepSeek, GLM, Kimi).",
    "description": "Drop-in replacement for the OpenAI API. Point any OpenAI SDK at https://onefreeapi.cloud/v1 and authenticate with sk-ofa-.... Supports streaming, tool calling, structured output, and returns OpenAI-shaped errors with machine-readable codes.",
    "contact": {
      "name": "OneFreeAPI",
      "url": "https://onefreeapi.cloud"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://onefreeapi.cloud",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "chat",
      "description": "Chat completions"
    },
    {
      "name": "models",
      "description": "Model discovery"
    },
    {
      "name": "meta",
      "description": "Health and discovery"
    }
  ],
  "paths": {
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "chat"
        ],
        "summary": "Create a chat completion",
        "operationId": "createChatCompletion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion, or an SSE stream when stream=true",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "data: {...} chunks, terminated by data: [DONE]"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Bad or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Unknown model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted or rate limited; honour Retry-After when present",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Upstream failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Upstream circuit breaker open",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "List models and validate the API key",
        "operationId": "listModels",
        "description": "Requires a valid key, so it doubles as a credential check: a bad key returns 401.",
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bad or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/models/{model}": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "Retrieve one model",
        "operationId": "getModel",
        "parameters": [
          {
            "name": "model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "bare": {
                "value": "glm-4-flash"
              },
              "prefixed": {
                "value": "openai/glm-4-flash"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "404": {
            "description": "Unknown model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "description": "Look up a single model. Model ids are prefix-tolerant: `glm-4-flash`, `openai/glm-4-flash` and `openai%2Fglm-4-flash` all resolve to `glm-4-flash`. Unknown ids return 404 `model_not_found`."
      }
    },
    "/v1/public/models": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "List models without authentication",
        "operationId": "listPublicModels",
        "security": [],
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Liveness probe",
        "operationId": "health",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sk-ofa-...",
        "description": "API key from https://onefreeapi.cloud/dashboard"
      }
    },
    "schemas": {
      "ChatMessage": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "tool_call_id": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Bare model id, e.g. glm-4-flash. Provider prefixes such as openai/ are tolerated.",
            "examples": [
              "glm-4-flash"
            ]
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            },
            "minItems": 1
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Return text/event-stream; terminated by data: [DONE]."
          },
          "stream_options": {
            "type": "object",
            "properties": {
              "include_usage": {
                "type": "boolean"
              }
            }
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "max_completion_tokens": {
            "type": "integer",
            "minimum": 1,
            "description": "Accepted as an alias of max_tokens."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "Forwarded unchanged to the upstream model."
          },
          "tool_choice": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "additionalProperties": true
              }
            ]
          },
          "parallel_tool_calls": {
            "type": "boolean"
          },
          "response_format": {
            "type": "object",
            "additionalProperties": true,
            "description": "json_object or json_schema, forwarded upstream."
          },
          "stop": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string",
            "description": "Canonical model id (prefixes stripped)."
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": "string",
                  "examples": [
                    "stop",
                    "length",
                    "tool_calls"
                  ]
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "glm-4-flash"
            ]
          },
          "object": {
            "type": "string",
            "const": "model"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          },
          "context_window": {
            "type": "integer"
          },
          "pricing": {
            "type": "object",
            "properties": {
              "input_per_1k": {
                "type": "number",
                "description": "Credits per 1K input tokens. 1000 credits = 1 USD."
              },
              "output_per_1k": {
                "type": "number"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "examples": [
                  "invalid_request_error",
                  "authentication_error",
                  "forbidden",
                  "rate_limit_exceeded",
                  "insufficient_quota",
                  "upstream_error",
                  "server_error"
                ]
              },
              "code": {
                "type": [
                  "string",
                  "null"
                ],
                "examples": [
                  "missing_api_key",
                  "invalid_api_key",
                  "invalid_api_key_format",
                  "model_not_found",
                  "insufficient_quota",
                  "daily_limit_reached",
                  "rate_limit_exceeded",
                  "upstream_rate_limited",
                  "upstream_unavailable",
                  "route_not_found"
                ]
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "request_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Same value as the x-request-id response header."
              }
            },
            "required": [
              "message",
              "type"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}