{
  "openapi": "3.1.0",
  "info": {
    "title": "BRAINIALL Diarized Transcription API",
    "version": "1.0.0",
    "description": "Transcribe one explicitly authorized Brazilian Portuguese or Spanish recording into JSON with word timestamps and speaker labels. This is an external metered service. Confirm recording rights and any required speaker notice or consent before selecting a file. Do not automatically retry an ambiguous upload; inspect account usage first.",
    "contact": {
      "name": "BRAINIALL",
      "url": "https://app.brainiall.com"
    },
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    }
  },
  "externalDocs": {
    "description": "Safe client, caption QA, and integration assets",
    "url": "https://github.com/fasuizu-br/brainiall-transcription-skill"
  },
  "servers": [
    {
      "url": "https://api.brainiall.com",
      "description": "BRAINIALL production API"
    }
  ],
  "tags": [
    {
      "name": "Transcription",
      "description": "Authorized audio or video transcription"
    }
  ],
  "paths": {
    "/v1/whisper/transcribe": {
      "post": {
        "operationId": "transcribeAuthorizedRecording",
        "summary": "Transcribe one authorized recording",
        "description": "Sends one potentially metered multipart request. The caller is responsible for verifying rights and any required speaker consent before sending media. A successful response still requires human review of words, timestamps, and speaker labels.",
        "tags": [
          "Transcription"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "audio",
                  "language",
                  "diarize"
                ],
                "properties": {
                  "audio": {
                    "type": "string",
                    "contentEncoding": "binary",
                    "description": "One local authorized .mp3, .wav, .m4a, .mp4, .mpeg, .mpga, .webm, or .ogg recording. The bundled safe client limits the file to 25 MB."
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "pt",
                      "es"
                    ],
                    "description": "pt for Brazilian Portuguese or es for Spanish."
                  },
                  "diarize": {
                    "type": "boolean",
                    "const": true,
                    "default": true,
                    "description": "Request speaker diarization. Speaker labels are anonymous turn labels, not biometric identity."
                  }
                }
              },
              "encoding": {
                "audio": {
                  "contentType": "audio/mpeg, audio/wav, audio/mp4, video/mp4, video/mpeg, audio/ogg, audio/webm"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Timestamped transcription. Review before operational use.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transcript"
                },
                "example": {
                  "text": "Bom dia. Hola!",
                  "words": [
                    {
                      "word": "Bom",
                      "start": 0,
                      "end": 0.2,
                      "speaker": "SPEAKER_00"
                    },
                    {
                      "word": "Hola",
                      "start": 1,
                      "end": 1.3,
                      "speaker": "SPEAKER_01"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthenticationError"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "413": {
            "$ref": "#/components/responses/MediaTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        },
        "x-brainiall-safety": {
          "rightsAndConsentRequiredBeforeRequest": true,
          "automaticRetryAllowed": false,
          "humanReviewRequired": true,
          "speakerLabelsAreBiometricIdentity": false
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "BRAINIALL API key",
        "description": "Use a dedicated revocable API key. Never place it in a shared specification, URL, source file, or committed environment."
      }
    },
    "schemas": {
      "Transcript": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "words"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Full transcript text when available."
          },
          "words": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Word"
            }
          }
        }
      },
      "Word": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "start",
          "end",
          "speaker"
        ],
        "anyOf": [
          {
            "required": [
              "word"
            ]
          },
          {
            "required": [
              "text"
            ]
          }
        ],
        "properties": {
          "word": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "start": {
            "type": "number",
            "minimum": 0
          },
          "end": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "speaker": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ],
            "description": "Anonymous speaker or turn label; not verified identity."
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "AuthenticationError": {
        "description": "API key missing or rejected.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InsufficientBalance": {
        "description": "Account has insufficient balance.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MediaTooLarge": {
        "description": "Media size was rejected.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit reached.",
        "headers": {
          "Retry-After": {
            "description": "Server-provided wait when present. A potentially uploaded request must not be replayed automatically.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceError": {
        "description": "Service unavailable. Inspect account usage before considering a manual retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}