---
title: "Create a new job"
method: POST
path: "/jobs"
---

# Create a new job

`POST /jobs`

## Request

- Base URL: `https://eu1.asr.api.speechmatics.com/v2`
- URL: `https://eu1.asr.api.speechmatics.com/v2/jobs`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/speechmatics/apis/speechmatics-asr-rest-api/docs/jobs/post.ts> (a function with typed inputs; its response is checked against the schema)

## Query parameters

- `wait` integer
- `format` 'json-v2' | 'txt' | 'srt'

## Headers

- `X-SM-Processing-Data` string

## Request body `multipart/form-data`

- object
  - `config` string, required: JSON containing a `JobConfig` model indicating the type and parameters for the recognition job.
  - `data_file` string, binary: The data file to be processed. Alternatively the data file can be fetched from a url specified in `JobConfig`.

## Response `201`

OK

- CreateJobResponse
  - `id` string, required: The unique ID assigned to the job. Keep a record of this for later retrieval of your completed job.
  - `status` 'created' | 'done' | 'rejected' | 'deleted': **Note**: Only available on SaaS on Cloud. Present only when the `wait` query parameter is set. Reports the outcome of the wait, which is distinct from the job lifecycle status returned by `GET /jobs/{jobid}`. * `created` - the job was created and is still running, or `wait` elapsed before it finished. * `done` - the job finished; the transcript is embedded under the requested `format` key when available. * `rejected` - the job could not be processed. * `deleted` - the job was deleted before it could finish.
  - `json-v2` RetrieveTranscriptResponse
    - `format` string, required: Speechmatics JSON transcript format version number.
    - `job` JobInfo, required: Summary information about an ASR job, to support identification and tracking.
      - `created_at` string, date-time, required: The UTC date time the job was created.
      - `data_name` string, required: Name of data file submitted for job.
      - `duration` integer, required: The data file audio duration (in seconds).
      - `id` string, required: The unique id assigned to the job.
      - `tracking` TrackingData
        - `title` string: The title of the job.
        - `reference` string: External system reference.
        - `tags` string[]
        - `details` object: Customer-defined JSON structure.
    - `metadata` RecognitionMetadata, required: Summary information about the output from an ASR job, comprising the job type and configuration parameters used when generating the output.
      - `created_at` string, date-time, required: The UTC date time the transcription output was created.
      - `type` 'transcription', required
      - `transcription_config` TranscriptionConfig
        - `language` string, required: Language model to process the audio input, normally specified as an ISO language code
        - `domain` string: Request a specialized model based on 'language' but optimized for a particular field, e.g. 'finance' or 'medical'.
        - `output_locale` string: Language locale to be used when generating the transcription output, normally specified as an ISO language code
        - `model` 'standard' | 'enhanced' | 'melia-1': Specific model to use in transcription (previously called operating point).
        - `operating_point` 'standard' | 'enhanced' | 'melia-1'
        - `additional_vocab` object[]: List of custom words or phrases that should be recognized. Alternative pronunciations can be specified to aid recognition.
          - `content` string, required
          - `sounds_like` string[]
        - `punctuation_overrides` object: Control punctuation settings.
          - `sensitivity` number, float: Ranges between zero and one. Higher values will produce more punctuation. The default is 0.5.
          - `permitted_marks` string[]: The punctuation marks which the client is prepared to accept in transcription output, or the special value 'all' (the default). Unsupported marks are ignored. This value is used to guide the transcription process.
        - `diarization` 'none' | 'speaker' | 'channel': Specify whether speaker or channel labels are added to the transcript. The default is `none`. - **none**: no speaker or channel labels are added. - **speaker**: speaker attribution is performed based on acoustic matching; all input channels are mixed into a single stream for processing. - **channel**: multiple input channels are processed individually and collated into a single transcript.
        - `channel_diarization_labels` string[]: Transcript labels to use when using collating separate input channels.
        - `enable_entities` boolean: Include additional 'entity' objects in the transcription results (e.g. dates, numbers) and their original spoken form. These entities are interleaved with other types of results. The concatenation of these words is represented as a single entity with the concatenated written form present in the 'content' field. The entities contain a 'spoken_form' field, which can be used in place of the corresponding 'word' type results, in case a spoken form is preferred to a written form. They also contain a 'written_form', which can be used instead of the entity, if you want a breakdown of the words without spaces. They can still contain non-breaking spaces and other special whitespace characters, as they are considered part of the word for the formatting output. In case of a written_form, the individual word times are estimated and might not be accurate if the order of the words in the written form does not correspond to the order they were actually spoken (such as 'one hundred million dollars' and '$100 million').
        - `max_delay_mode` 'fixed' | 'flexible': Whether or not to enable flexible endpointing and allow the entity to continue to be spoken.
        - `audio_filtering_config` object: Configuration for limiting the transcription of quiet audio.
          - `volume_threshold` number, float: Controls the lower limit of audio volume at which speech and audio events will be transcribed. If the volume limit is very low, then most sound will be passed to the speech recognition engine. Higher numbers will cut out increasing amounts of sound.
        - `transcript_filtering_config` object: Configuration for applying filtering to the transcription
          - `remove_disfluencies` boolean: If true, words that are identified as disfluencies will be removed from the transcript. If false (default), they are tagged in the transcript as 'disfluency'.
          - `replacements` object[]: An array of objects defining custom replacements. Each replacement contains a pair of strings: the text to find `from` and the text to replace it with `to`.
            - `from` string, required
            - `to` string, required
        - `speaker_diarization_config` object: Configuration for speaker diarization
          - `prefer_current_speaker` boolean: If true, the algorithm will prefer to stay with the current active speaker if it is a close enough match, even if other speakers may be closer. This is useful for cases where we can flip incorrectly between similar speakers during a single speaker section.
          - `speaker_sensitivity` number, float: Controls how sensitive the algorithm is in terms of keeping similar speakers separate, as opposed to combining them into a single speaker. Higher values will typically lead to more speakers, as the degree of difference between speakers in order to allow them to remain distinct will be lower. A lower value for this parameter will conversely guide the algorithm towards being less sensitive in terms of retaining similar speakers, and as such may lead to fewer speakers overall. The default is 0.5.
          - `get_speakers` boolean: If true, speaker identifiers will be returned at the end of transcript.
          - `speakers` SpeakersInputItem[]: Use this option to provide speaker labels linked to their speaker identifiers. When passed, the transcription system will tag spoken words in the transcript with the provided speaker labels whenever any of the specified speakers is detected in the audio. A maximum of 50 speakers identifiers across all speakers can be provided.
            - `label` string, required: Speaker label, which must not match the format used internally (e.g. S1, S2, etc)
            - `speaker_identifiers` string[], required
      - `translation_errors` TranslationError[]: List of errors that occurred in the translation stage.
        - `type` 'translation_failed' | 'unsupported_translation_pair'
        - `message` string: Human readable error message
      - `summarization_errors` SummarizationError[]: List of errors that occurred in the summarization stage.
        - `type` 'summarization_failed' | 'unsupported_language'
        - `message` string: Human readable error message
      - `sentiment_analysis_errors` SentimentAnalysisError[]: List of errors that occurred in the sentiment analysis stage.
        - `type` 'sentiment_analysis_failed' | 'unsupported_language'
        - `message` string: Human readable error message
      - `topic_detection_errors` TopicDetectionError[]: List of errors that occurred in the topic detection stage.
        - `type` 'topic_detection_failed' | 'unsupported_list_of_topics' | 'unsupported_language'
        - `message` string: Human readable error message
      - `auto_chapters_errors` AutoChaptersResultError[]: List of errors that occurred in the auto chapters stage.
        - `type` 'auto_chapters_failed' | 'unsupported_language'
        - `message` string: Human readable error message
      - `output_config` OutputConfig
        - `srt_overrides` object: Parameters that override default values of srt conversion. max_line_length: sets maximum count of characters per subtitle line including white space. max_lines: sets maximum count of lines in a subtitle section.
          - `max_line_length` integer
          - `max_lines` integer
      - `language_pack_info` LanguagePackInfo: Properties of the language pack.
        - `language_description` string: Full descriptive name of the language, e.g. 'Japanese'.
        - `word_delimiter` string, required: The character to use to separate words.
        - `writing_direction` 'left-to-right' | 'right-to-left': The direction that words in the language should be written and read in.
        - `itn` boolean: Whether or not ITN (inverse text normalization) is available for the language pack.
        - `adapted` boolean: Whether or not language model adaptation has been applied to the language pack.
      - `language_identification` LanguageIdentificationResult
        - `results` LanguageIdentificationResultItem[]
          - `alternatives` LanguageIdentificationResultAlternative[]
            - `language` string
            - `confidence` number
          - `start_time` number
          - `end_time` number
        - `error` 'LOW_CONFIDENCE' | 'UNEXPECTED_LANGUAGE' | 'NO_SPEECH' | 'FILE_UNREADABLE' | 'OTHER'
        - `message` string
      - `orchestrator_version` string: Orchestrator version in PEP 440 Format or set to 'version_not_found' as default.
    - `results` RecognitionResult[], required
      - `channel` string
      - `start_time` number, float, required
      - `end_time` number, float, required
      - `volume` number, float: An indication of the volume of audio across the time period the word was spoken.
      - `is_eos` boolean: Whether the punctuation mark is an end of sentence character. Only applies to punctuation marks.
      - `type` 'word' | 'punctuation' | 'entity', required: New types of items may appear without being requested; unrecognized item types can be ignored.
      - `written_form` WrittenFormRecognitionResult[]
        - `alternatives` RecognitionAlternative[], required
          - `content` string, required
          - `confidence` number, float, required
          - `language` string, required
          - `display` RecognitionDisplay
            - `direction` 'ltr' | 'rtl', required
          - `speaker` string
          - `tags` string[]
        - `end_time` number, float, required
        - `start_time` number, float, required
        - `type` 'word', required: What kind of object this is. See #/Definitions/RecognitionResult for definitions of the enums.
      - `spoken_form` SpokenFormRecognitionResult[]
        - `alternatives` RecognitionAlternative[], required
          - `content` string, required
          - `confidence` number, float, required
          - `language` string, required
          - `display` RecognitionDisplay
            - `direction` 'ltr' | 'rtl', required
          - `speaker` string
          - `tags` string[]
        - `end_time` number, float, required
        - `start_time` number, float, required
        - `type` 'word' | 'punctuation', required: What kind of object this is. See #/Definitions/RecognitionResult for definitions of the enums.
      - `alternatives` RecognitionAlternative[]
        - `content` string, required
        - `confidence` number, float, required
        - `language` string, required
        - `display` RecognitionDisplay
          - `direction` 'ltr' | 'rtl', required
        - `speaker` string
        - `tags` string[]
      - `attaches_to` 'previous' | 'next' | 'both' | 'none': Attachment direction of the punctuation mark. This only applies to punctuation marks. This information can be used to produce a well-formed text representation by placing the `word_delimiter` from `language_pack_info` on the correct side of the punctuation mark.
    - `speakers` SpeakersResultItem[]: List of unique speaker identifiers detected in the transcript.
      - `label` string, required: Speaker label.
      - `speaker_identifiers` string[], required
    - `translations` object: Translations of the transcript into other languages. It is a map of ISO language codes to arrays of translated sentences. Configured using `translation_config`.
    - `summary` SummarizationResult: Summary of the transcript, configured using `summarization_config`.
      - `content` string
    - `sentiment_analysis` SentimentAnalysisResult: The main object that holds sentiment analysis data.
      - `sentiment_analysis` object: Holds the detailed sentiment analysis information.
        - `segments` SentimentSegment[]: An array of objects that represent a segment of text and its associated sentiment.
          - `text` string: Represents the transcript of the analysed segment
          - `sentiment` string: The assigned sentiment to the segment, which can be positive, neutral or negative
          - `start_time` number, float: The timestamp corresponding to the beginning of the transcription segment
          - `end_time` number, float: The timestamp corresponding to the end of the transcription segment
          - `speaker` string: The speaker label for the segment, if speaker diarization is enabled
          - `channel` string: The channel label for the segment, if channel diarization is enabled
          - `confidence` unknown
        - `summary` SentimentSummary: Holds overall sentiment information, as well as detailed per-speaker and per-channel sentiment data.
          - `overall` SentimentSummaryDetail: Holds the count of sentiment information grouped by positive, neutral and negative.
            - `positive_count` integer
            - `negative_count` integer
            - `neutral_count` integer
          - `speakers` SentimentSpeakerSummary[]: An array of objects that represent sentiment data for a specific speaker.
            - `speaker` string
            - `positive_count` integer
            - `negative_count` integer
            - `neutral_count` integer
          - `channels` SentimentChannelSummary[]: An array of objects that represent sentiment data for a specific channel.
            - `channel` string
            - `positive_count` integer
            - `negative_count` integer
            - `neutral_count` integer
    - `topics` TopicDetectionResult: Main object that holds topic detection results.
      - `segments` TopicDetectionSegment[]: An array of objects that represent a segment of text and its associated topic information.
        - `text` string
        - `start_time` number, float
        - `end_time` number, float
        - `topics` TopicDetectionSegmentTopic[]
          - `topic` string
      - `summary` TopicDetectionSummary: Holds overall information on the topics detected.
        - `overall` TopicDetectionSummaryOverall: Holds the count of topics detected.
    - `chapters` Chapter[]: An array of objects that represent summarized chapters of the transcript
      - `title` string: The auto-generated title for the chapter
      - `summary` string: An auto-generated paragraph-style, short summary of the chapter
      - `start_time` number: The start time of the chapter in the audio file
      - `end_time` number
    - `audio_events` AudioEventItem[]: Timestamped audio events, only set if `audio_events_config` is in the config
      - `type` string: Kind of audio event. E.g. music
      - `start_time` number, float: Time (in seconds) at which the audio event starts
      - `end_time` number, float: Time (in seconds) at which the audio event ends
      - `confidence` number, float: Prediction confidence associated with this event
      - `channel` string: Input channel this event occurred on
    - `audio_event_summary` object: Summary statistics per event type, keyed by `type`, e.g. music
      - `overall` AudioEventSummary
      - `channels` object: Summary keyed by channel, only set if channel diarization is enabled
  - `txt` string: **Note**: Only available on SaaS on Cloud. The transcript in plain text, embedded when `status` is `done` and `format` was `txt`. Best-effort: if absent, fetch it from `GET /jobs/{jobid}/transcript`.
  - `srt` string: **Note**: Only available on SaaS on Cloud. The transcript in SRT format, embedded when `status` is `done` and `format` was `srt`. Best-effort: if absent, fetch it from `GET /jobs/{jobid}/transcript`.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Rate Limited
- `500`: Internal Server Error

---

[API](https://skmtc.dev/speechmatics/apis/speechmatics-asr-rest-api.md) - [All operations](https://skmtc.dev/speechmatics/apis/speechmatics-asr-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/speechmatics/apis/speechmatics-asr-rest-api/revisions/32c77b5e2177?raw)