openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "ASMR Audio Preprocessor API",
    "version": "1.0.0",
    "description": "Upload audio, automatically accept all detected channel repairs, and return the fully processed WAV in one synchronous request."
  },
  "servers": [
    {
      "url": "/",
      "description": "Current API server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "getHealth",
        "summary": "Process liveness (does not probe FFmpeg)",
        "security": [],
        "responses": {
          "200": {
            "description": "Server is running.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApi",
        "summary": "Download this OpenAPI document",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.0.3 document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/process": {
      "post": {
        "operationId": "processAudio",
        "summary": "Analyze and process uploaded audio without manual review",
        "description": "Accepts WAV, MP3, M4A, AAC, OGG and FLAC. Returns 48 kHz, 16-bit PCM stereo WAV after the entire processing chain completes. Omitted options use the workbench defaults. Files are deleted after the response or failure. No queue or persistent result is created.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "audio"
                ],
                "properties": {
                  "audio": {
                    "type": "string",
                    "format": "binary",
                    "description": "Exactly one non-empty audio file, with a supported filename extension."
                  },
                  "options": {
                    "$ref": "#/components/schemas/ProcessOptions"
                  }
                }
              },
              "encoding": {
                "options": {
                  "contentType": "application/json"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed audio download. All detected segments have been accepted automatically.",
            "headers": {
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                },
                "description": "attachment; filename=\"processed.wav\""
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier."
              },
              "X-Audio-Duration": {
                "schema": {
                  "type": "number"
                },
                "description": "Probed source duration in seconds."
              },
              "X-Detected-Segments": {
                "schema": {
                  "type": "integer"
                },
                "description": "Number of automatically accepted repair segments."
              }
            },
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Missing audio, malformed multipart/JSON, duplicate or unknown fields, or invalid option values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Bearer realm=\"audio-api\""
              }
            }
          },
          "408": {
            "description": "Upload timeout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Audio upload, options field, request body, or audio duration exceeds configured limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported request media type or filename extension.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Audio metadata cannot be read, or duration is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Audio processing or temporary file storage failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Server busy or shutting down.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds before retrying a busy server (5)."
              }
            }
          },
          "504": {
            "description": "Processing timeout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The server API_TOKEN value."
      }
    },
    "schemas": {
      "ProcessOptions": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "sensitivity": {
            "type": "number",
            "minimum": 40,
            "maximum": 95,
            "default": 76,
            "description": "Channel anomaly detection sensitivity."
          },
          "minimumDuration": {
            "type": "number",
            "minimum": 0.2,
            "maximum": 4.8,
            "default": 1.2,
            "description": "Minimum sustained anomaly duration in seconds; transient detection is independent."
          },
          "fallbackSensitivity": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 30,
            "description": "One-sided loudness fallback sensitivity; zero disables it."
          },
          "noiseReduction": {
            "type": "object",
            "additionalProperties": false,
            "default": {},
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": true
              },
              "strength": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "default": 72
              }
            }
          },
          "voiceEnhancement": {
            "type": "object",
            "additionalProperties": false,
            "default": {},
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": false
              },
              "strength": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "default": 55
              }
            }
          },
          "secondStage": {
            "type": "object",
            "additionalProperties": false,
            "default": {},
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": true
              },
              "mergeChannels": {
                "type": "boolean",
                "default": true
              },
              "noiseReduction": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "default": 64
              },
              "voiceRepair": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "default": 48
              },
              "voicePresence": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "default": 42
              },
              "loudnessCompensation": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "default": 42
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "requestId"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": "string"
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}