{
  "openapi": "3.0.3",
  "info": {"title": "Transcription API", "version": "1.1.0", "description": "Full-recording asynchronous transcription with existing TTS API keys. Poll every 5 seconds. No webhooks. Export without a second recognition charge. Results expire 90 days after creation. Errors expose code, message, details and retryable. A failed task is terminal; a new attempt requires a new Idempotency-Key and may incur a new charge."},
  "servers": [{"url": "https://zvukogram.com/api/v1"}],
  "security": [{"bearerKey": []}, {"headerKey": []}],
  "paths": {
    "/transcription-models": {"get": {
      "operationId": "listTranscriptionModels",
      "responses": {
        "200": {"description": "Publicly enabled and configured models", "content": {"application/json": {"schema": {"type": "object", "required": ["models", "export_formats"], "properties": {
          "models": {"type": "array", "items": {"$ref": "#/components/schemas/Model"}},
          "export_formats": {"type": "array", "items": {"$ref": "#/components/schemas/ExportFormat"}}
        }}}}}, "default": {"$ref": "#/components/responses/Error"}
      }
    }},
    "/transcriptions": {"post": {
      "operationId": "createTranscription",
      "description": "One file per request. Upload is a single multipart request; server processes media asynchronously. Alternatively submit a direct public HTTPS URL as JSON. Legacy POST credentials email/token are also accepted. Idempotency covers the same model, language, filename and bytes or URL for one account during retention. Different input with the same key returns 409.",
      "parameters": [{"name": "Idempotency-Key", "in": "header", "schema": {"type": "string", "maxLength": 200}, "description": "Recommended. Stable across retries of the same upload. No whitespace/control characters."}],
      "requestBody": {"required": true, "content": {
        "multipart/form-data": {"schema": {"type": "object", "additionalProperties": false, "required": ["model", "file"], "properties": {
          "model": {"type": "string", "description": "Current id from the model catalogue. Previous public names and the permanent model code remain accepted.", "example": "azure-fast"}, "language": {"type": "string", "default": "ru-RU"},
          "file": {"type": "string", "format": "binary"}, "email": {"type": "string"}, "token": {"type": "string"}
        }}},
        "application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["model", "source_url"], "properties": {
          "model": {"type": "string", "description": "Current id from the model catalogue. Previous public names and the permanent model code remain accepted.", "example": "azure-fast"}, "language": {"type": "string", "default": "ru-RU"},
          "source_url": {"type": "string", "format": "uri", "example": "https://files.example.org/audio.mp3"}, "email": {"type": "string"}, "token": {"type": "string"}
        }}}
      }},
      "responses": {
        "202": {"description": "Upload saved or URL queued; a replay returns the existing task", "headers": {"Location": {"schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Task"}}}},
        "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"},
        "409": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "415": {"$ref": "#/components/responses/Error"},
        "429": {"$ref": "#/components/responses/RateLimit"}, "503": {"$ref": "#/components/responses/Error"}, "default": {"$ref": "#/components/responses/Error"}
      }
    }},
    "/transcriptions/{id}": {"parameters": [{"$ref": "#/components/parameters/TaskId"}], "get": {
      "operationId": "getTranscription",
      "responses": {
        "200": {"description": "Current task state; asynchronous failures are reported in error", "headers": {"Retry-After": {"schema": {"type": "integer", "example": 5}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Task"}}}},
        "404": {"$ref": "#/components/responses/Error"}, "429": {"$ref": "#/components/responses/RateLimit"}, "default": {"$ref": "#/components/responses/Error"}
      }
    }},
    "/transcriptions/{id}/result": {"parameters": [{"$ref": "#/components/parameters/TaskId"}], "get": {
      "operationId": "getTranscriptionResult",
      "responses": {
        "200": {"description": "Normalized full transcript; all timestamps are milliseconds", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Transcript"}}}},
        "409": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "default": {"$ref": "#/components/responses/Error"}
      }
    }},
    "/transcriptions/{id}/export": {"parameters": [{"$ref": "#/components/parameters/TaskId"}], "get": {
      "operationId": "exportTranscription",
      "parameters": [{"name": "format", "in": "query", "schema": {"$ref": "#/components/schemas/ExportFormat"}, "description": "Default txt. Generated and cached on first request."}],
      "responses": {
        "200": {"description": "Attachment in the requested format", "headers": {"Content-Disposition": {"schema": {"type": "string"}}}, "content": {
          "application/pdf": {"schema": {"type": "string", "format": "binary"}},
          "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {"schema": {"type": "string", "format": "binary"}},
          "application/json": {"schema": {"$ref": "#/components/schemas/Transcript"}},
          "text/plain": {"schema": {"type": "string"}}, "application/x-subrip": {"schema": {"type": "string"}},
          "text/vtt": {"schema": {"type": "string"}}, "text/csv": {"schema": {"type": "string"}}
        }},
        "400": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "default": {"$ref": "#/components/responses/Error"}
      }
    }}
  },
  "components": {
    "securitySchemes": {"bearerKey": {"type": "http", "scheme": "bearer"}, "headerKey": {"type": "apiKey", "in": "header", "name": "X-API-Key"}},
    "parameters": {"TaskId": {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-f0-9]{32}$"}}},
    "responses": {
      "Error": {"description": "Structured API error. Before acceptance use the HTTP status; after 202 poll Task.error with HTTP 200. Fetching result/export for a failed task returns HTTP 409 task_failed with details.task_error. Proxy errors before PHP may have another response format.", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"$ref": "#/components/schemas/Error"}}}}}},
      "RateLimit": {"description": "20 creations or 120 reads per minute, or 20 active tasks per account", "headers": {"Retry-After": {"schema": {"type": "integer", "example": 60}}}, "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"$ref": "#/components/schemas/Error"}}}}}}
    },
    "schemas": {
      "ExportFormat": {"type": "string", "enum": ["txt", "json", "srt", "vtt", "sub", "pdf", "docx", "csv"]},
      "Error": {"type": "object", "required": ["code", "message", "details", "retryable"], "properties": {
        "code": {"type": "string", "description": "Stable machine-readable cause; handle unknown future codes with a fallback."},
        "message": {"type": "string", "description": "Human-readable message, not intended for programmatic parsing."},
        "details": {"$ref": "#/components/schemas/ErrorDetails"},
        "retryable": {"type": "boolean", "description": "Cause may be transient. Does not restart a terminal task. Poll result_not_ready; retry failed tasks only deliberately with a new idempotency key. Provider connection errors can have an unknown remote outcome."}
      }, "example": {"code":"file_too_large","message":"File exceeds the upload limit for model azure-mai: 300000000 bytes.","details":{"model":"azure-mai","max_bytes":300000000,"max_duration_seconds":7200,"actual_bytes":1013046414,"stage":"download"},"retryable":false}},
      "ErrorDetails": {"type":"object", "additionalProperties":true, "description":"Optional fields captured at failure time. Historical tasks may have no details. All byte limits use bytes; duration limits use seconds.", "properties": {
        "model":{"type":"string"}, "max_bytes":{"type":"integer","format":"int64"},
        "actual_bytes":{"type":"integer","format":"int64","description":"Local file size or size declared by the source server."},
        "received_bytes":{"type":"integer","format":"int64","description":"Bytes observed when a streaming size limit was exceeded; not the complete file size."},
        "max_duration_seconds":{"type":"integer"}, "duration_seconds":{"type":"integer"}, "max_request_bytes":{"type":"integer","format":"int64"},
        "source_http_status":{"type":"integer"}, "timeout_seconds":{"type":"integer"}, "stage":{"type":"string"},
        "required_tokens":{"type":"number"}, "available_tokens":{"type":"number"}, "missing_tokens":{"type":"number"},
        "limit":{"type":"integer"}, "window_seconds":{"type":"integer"}, "retry_after_seconds":{"type":"integer"},
        "field":{"type":"string"}, "allowed_methods":{"type":"array","items":{"type":"string"}},
        "allowed_formats":{"type":"array","items":{"$ref":"#/components/schemas/ExportFormat"}},
        "php_upload_max_bytes":{"type":"integer","format":"int64"}, "php_post_max_bytes":{"type":"integer","format":"int64"},
        "task_status":{"type":"string"}, "task_error":{"$ref":"#/components/schemas/Error"}
      }},
      "Task": {"type": "object", "required": ["id", "status", "created_at", "expires_at", "duration_seconds", "cost_tokens", "refunded", "error"], "properties": {
        "id": {"type": "string"}, "status": {"type": "string", "enum": ["queued", "downloading", "validating", "processing", "completed", "failed"]},
        "created_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"},
        "duration_seconds": {"type": "integer", "nullable": true}, "cost_tokens": {"type": "number", "nullable": true}, "refunded": {"type": "boolean"},
        "error": {"type": "object", "nullable": true, "required":["code","message","details","retryable"], "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "details":{"$ref":"#/components/schemas/ErrorDetails"}, "retryable":{"type":"boolean"}}}
      }},
      "Model": {"type": "object", "properties": {
        "id": {"type": "string", "description": "Current public API name. Only the latest selected name is listed; historical names and the permanent code still resolve to this model."}, "name": {"type": "string"}, "languages": {"type": "array", "items": {"type": "string"}},
        "auto_language": {"type": "boolean"}, "max_bytes": {"type": "integer", "format": "int64", "description":"Maximum original upload or URL download size, before conversion."},
        "max_request_bytes": {"type":"integer", "format":"int64", "description":"Maximum prepared audio size sent to the provider, checked after server-side conversion. Clients do not have to convert media themselves."},
        "max_duration_seconds": {"type": "integer"}, "price_tokens_per_minute": {"type": "number"}
      }},
      "Transcript": {"type": "object", "required": ["id", "schema_version", "text", "language", "duration_seconds", "no_speech", "segments", "speakers"], "properties": {
        "id": {"type": "string"}, "schema_version": {"type": "integer", "enum": [1]}, "text": {"type": "string"},
        "language": {"type": "string"}, "duration_seconds": {"type": "integer"}, "no_speech": {"type": "boolean"},
        "segments": {"type": "array", "items": {"type": "object", "properties": {
          "text": {"type": "string"}, "start_ms": {"type": "integer"}, "end_ms": {"type": "integer"}, "speaker_id": {"type": "string"},
          "words": {"type": "array", "items": {"type": "object", "properties": {"text": {"type": "string"}, "start_ms": {"type": "integer"}, "end_ms": {"type": "integer"}}}}
        }}},
        "speakers": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}}}}
      }}
    }
  }
}
