Salad Transcription Job

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/api-evangelist/salad-transcription-api/json-schema/salad-transcription-job-schema.json",
  "title": "Salad Transcription Job",
  "description": "Schema for a Salad Transcription API job request and response.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the transcription job.",
      "example": "54e84442-3576-45ca-904c-a1d90bc77baf"
    },
    "input": {
      "type": "object",
      "description": "Input configuration for the transcription job.",
      "required": ["url"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL of the audio or video file to transcribe. Must be publicly accessible."
        },
        "language_code": {
          "type": "string",
          "description": "BCP-47 language code (e.g., 'en', 'fr', 'de'). Defaults to auto-detection.",
          "default": "en",
          "example": "en"
        },
        "word_level_timestamps": {
          "type": "boolean",
          "description": "Whether to include word-level timestamps in the output.",
          "default": false
        },
        "diarization": {
          "type": "boolean",
          "description": "Whether to identify and separate individual speakers.",
          "default": false
        },
        "srt": {
          "type": "boolean",
          "description": "Whether to generate SRT caption/subtitle output.",
          "default": false
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Optional user-provided metadata attached to the job.",
      "additionalProperties": true
    },
    "status": {
      "type": "string",
      "description": "Current status of the transcription job.",
      "enum": ["pending", "created", "running", "succeeded", "failed"]
    },
    "events": {
      "type": "array",
      "description": "Timeline of job status events.",
      "items": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "description": "Event action name.",
            "enum": ["created", "started", "succeeded", "failed"]
          },
          "time": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of the event."
          }
        }
      }
    },
    "output": {
      "type": "object",
      "description": "Transcription output (available when status is 'succeeded').",
      "properties": {
        "segments": {
          "type": "array",
          "description": "Array of transcribed segments.",
          "items": {
            "type": "object",
            "properties": {
              "start": { "type": "number", "description": "Start time in seconds." },
              "end": { "type": "number", "description": "End time in seconds." },
              "text": { "type": "string", "description": "Transcribed text for the segment." },
              "speaker": { "type": "string", "description": "Speaker label (when diarization is enabled)." },
              "words": {
                "type": "array",
                "description": "Word-level details (when word_level_timestamps is enabled).",
                "items": {
                  "type": "object",
                  "properties": {
                    "word": { "type": "string" },
                    "start": { "type": "number" },
                    "end": { "type": "number" },
                    "score": { "type": "number", "description": "Confidence score (0–1)." },
                    "speaker": { "type": "string" }
                  }
                }
              }
            }
          }
        },
        "srt_content": {
          "type": "string",
          "description": "SRT-formatted caption content (when srt is enabled)."
        },
        "duration": {
          "type": "number",
          "description": "Total duration of the media in seconds."
        },
        "processing_time": {
          "type": "number",
          "description": "Time taken to process the transcription in seconds."
        }
      }
    },
    "create_time": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the job was created."
    },
    "update_time": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of the last job update."
    }
  },
  "required": ["input"]
}