openapi: 3.0.1
info:
  termsOfService: https://www.rev.ai/about/terms
  title: Rev AI Language Identification
  contact:
    email: support@rev.ai
    name: Rev
    url: https://www.rev.ai/
  version: v1
  description: Rev AI Language Identification
  license:
    name: Rev AI Terms of Service
    url: https://www.rev.ai/about/terms
servers:
  - url: https://api.rev.ai
    description: Rev AI API
security:
  - AccessToken: []
paths:
  /languageid/v1/jobs:
    post:
      summary: Submit Language Identification Job
      operationId: SubmitLanguageIdentificationJob
      description: >
        Starts an asynchronous job to identify the most probable language in the
        audio. Audio can be specified in two ways, either by including a public
        url to the media via the `source_config` option or by uploading a local
        file as part of a multipart/form request.
      tags:
        - Jobs
      requestBody:
        description: Language Identification Job Options
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitLanguageIdentificationJobOptions'
            examples:
              JSON Submission:
                value:
                  metadata: sample user provided metadata
                  notification_config:
                    url: https://www.example.com/callback
                    auth_headers:
                      Authorization: Bearer <notification-url-token>
                  delete_after_seconds: 1000000
                  source_config:
                    url: https://www.rev.ai/FTC_Sample_1.mp3
                    auth_headers:
                      Authorization: Bearer <source-url-token>
          multipart/form-data:
            schema:
              type: object
              properties:
                media:
                  type: string
                  format: binary
                  description: >-
                    Limited to files less than 2GB in size. If the file is
                    larger than 2GB, submit a language id job using `media_url`.
                    **Note:** Media files longer than 17 hours or shorter than 2
                    seconds are not supported for Language Identification.
                options:
                  type: object
                  nullable: true
                  allOf:
                    - $ref: >-
                        #/components/schemas/SubmitLanguageIdentificationJobMultipartOptions
      responses:
        '200':
          description: Language Identification Job Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageIdentificationJob'
              examples:
                New Job:
                  $ref: '#/components/examples/NewLanguageIdentificationJob'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              examples:
                No Input Media Url:
                  $ref: '#/components/examples/BadRequestNoInputMediaUrl'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/HipaaForbiddenOrForbiddenDeployment'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
      x-code-samples:
        - lang: Shell
          label: curl
          source: >
            # Submit via media URL. URL must be publicly accessible and a direct
            link to media

            curl -X POST "https://api.rev.ai/languageid/v1/jobs" -H
            "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Content-Type:
            application/json" -d "{\"metadata\": \"sample user provided
            metadata\", \"notification_config\": {\"url\":
            \"https://www.example.com/callback\"}, \"delete_after_seconds\":
            1000000, \"source_config\": {\"url:\":
            \"https://www.rev.ai/FTC_Sample_1.mp3\"}"


            # Submit for local uploads.

            curl -X POST "https://api.rev.ai/languageid/v1/jobs" -H
            "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Content-Type:
            multipart/form-data" -F "media=@/path/to/media_file.mp3" -F
            "options={\"metadata\": \"sample user provided metadata\",
            \"notification_config\": {\"url\":
            \"https://www.example.com/callback\"}, \"delete_after_seconds\":
            1000000}"
    get:
      summary: Get List of Language Identification Jobs
      operationId: GetListOfLanguageIdentificationJobs
      description: >
        Gets a list of language identification jobs submitted within the last 30
        days in reverse chronological order up to the provided `limit` number of
        jobs per call. **Note:** Jobs older than 30 days will not be listed.
        Pagination is supported via passing the last job `id` from a previous
        call into `starting_after`.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/JobListLimit'
        - $ref: '#/components/parameters/JobListStartingAfter'
      responses:
        '200':
          description: List of Rev AI Language Identification Jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LanguageIdentificationJob'
              examples:
                Jobs Found:
                  value:
                    - id: Bmx5c8F5pH7a
                      status: in_progress
                      created_on: '2018-05-05T23:23:22.29Z'
                      type: language_id
                    - id: 6BxQYGa638Yt
                      status: completed
                      created_on: '2018-05-05T23:23:22.29Z'
                      completed_on: '2018-05-05T23:45:13.41Z'
                      type: language_id
                No Jobs Found:
                  value: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestProblemDetails'
              examples:
                Limit Above Max Value:
                  $ref: '#/components/examples/BadLimitResponse'
                Invalid Job Id:
                  $ref: '#/components/examples/InvalidStartingAfterResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
  /languageid/v1/jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Get Language Identification Job By Id
      operationId: GetLanguageIdentificationJobById
      description: Returns information about a language identification job.
      tags:
        - Jobs
      responses:
        '200':
          description: Language Identification Job Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageIdentificationJob'
              examples:
                New Job:
                  $ref: '#/components/examples/NewLanguageIdentificationJob'
                Completed Job:
                  $ref: '#/components/examples/CompletedLanguageIdentificationJob'
                Failed Job:
                  $ref: '#/components/examples/FailedLanguageIdentificationJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
    delete:
      summary: Delete Language Identification Job by Id
      operationId: DeleteLanguageIdentificationJobById
      description: >-
        Deletes a language identification job. All data related to the job will
        be permanently deleted. A job can only be deleted once it's completed
        (either with success or failure).
      tags:
        - Jobs
      responses:
        '204':
          $ref: '#/components/responses/DeleteJobSuccessful'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidStateDetails'
              examples:
                In Progress Job:
                  $ref: >-
                    #/components/examples/ConflictAudioAnalysisJob_InvalidDeleteState
  /languageid/v1/jobs/{id}/result:
    get:
      parameters:
        - $ref: '#/components/parameters/JobId'
      summary: Get Language Identification Result By Id
      operationId: GetLanguageIdentificationResultById
      description: |
        Returns the results for a completed language identification job.
      tags:
        - Jobs
      responses:
        '200':
          $ref: '#/components/responses/SampleLanguageIdentificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenDeployment'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidStateDetails'
              examples:
                In Progress Job:
                  $ref: >-
                    #/components/examples/ConflictAudioAnalysisJob_InvalidStateInProgress
                Failed Job:
                  $ref: >-
                    #/components/examples/ConflictAudioAnalysisJob_InvalidStateFailed
components:
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
  parameters:
    JobListLimit:
      in: query
      name: limit
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 0
        nullable: true
      required: false
      description: Limits the number of jobs returned, default is 100, max is 1000
    JobListStartingAfter:
      in: query
      name: starting_after
      schema:
        type: string
        nullable: true
      required: false
      description: >-
        If specified, returns jobs submitted before the job with this id,
        exclusive (job with this id is not included)
    JobId:
      name: id
      in: path
      description: Rev AI API Job Id
      required: true
      schema:
        type: string
  schemas:
    JobIdField:
      type: string
      description: Id of the job.
      example: Umx5c6F7pH7r
    CreatedOnField:
      type: string
      format: date-time
      description: The date and time the job was created in ISO-8601 UTC form.
      example: '2018-05-05T23:23:22.29Z'
    CompletedOnField:
      type: string
      format: date-time
      description: >-
        The date and time the job was completed, whether successfully or
        failing, in ISO-8601 UTC form.
      nullable: true
      example: '2018-05-05T23:28:22.29Z'
    MetadataField:
      type: string
      maxLength: 512
      description: Optional metadata that was provided during job submission.
      nullable: true
    FailureDetailField:
      type: string
      description: Human-readable reason why the job failed.
      nullable: true
      example: Internal server error.
    CallbackUrlField:
      deprecated: true
      type: string
      maxLength: 1024
      description: >
        *Deprecated. Use notification_config instead*. Optional callback url to
        invoke when processing is complete.

        If this parameter is used to pass in the callback url, the callback url
        will be visible in the response.

        It is recommended to provide webhooks with the `notification_config`
        parameter as authorization headers can be included

        and both the callback url and auth headers will be encrypted when
        stored.
      nullable: true
      example: https://www.example.com/callback
    DeleteAfterSecondsField:
      description: >-
        Amount of time after job completion when job is auto-deleted. Present
        only when preference set in job request.
      type: integer
      minimum: 0
      maximum: 2592000
      nullable: true
    BaseApiJob:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/JobIdField'
        created_on:
          $ref: '#/components/schemas/CreatedOnField'
        completed_on:
          $ref: '#/components/schemas/CompletedOnField'
        metadata:
          $ref: '#/components/schemas/MetadataField'
        failure_detail:
          $ref: '#/components/schemas/FailureDetailField'
        callback_url:
          $ref: '#/components/schemas/CallbackUrlField'
        delete_after_seconds:
          $ref: '#/components/schemas/DeleteAfterSecondsField'
    AudioAnalysisStatusField:
      type: string
      enum:
        - in_progress
        - completed
        - failed
      description: Current status of the job.
      example: completed
    AudioAnalysisFailureField:
      type: string
      description: >-
        Simple reason of why the job failed. Check `failure_detail` for specific
        details and solutions.
      enum:
        - internal_processing
        - insufficient_balance
        - invoicing_limit_exceeded
    AudioAnalysisMediaUrlField:
      deprecated: true
      type: string
      maxLength: 2048
      description: >
        <span class="hipaa-badge">**[HIPAA unsupported]**</span> *Deprecated.
        Use source_config instead.*

        Direct download media url.

        If this parameter is used to pass in the media url, the media url will
        be visible in the response.

        It is recommended to use the `source_config` parameter instead, as
        authorization headers can be included and both

        the source url and auth headers will be encrypted when stored.
      nullable: false
    BaseAudioAnalysisJob:
      allOf:
        - $ref: '#/components/schemas/BaseApiJob'
        - type: object
          properties:
            status:
              $ref: '#/components/schemas/AudioAnalysisStatusField'
            failure:
              $ref: '#/components/schemas/AudioAnalysisFailureField'
            media_url:
              $ref: '#/components/schemas/AudioAnalysisMediaUrlField'
    LanguageIdentificationJob:
      description: >
        Rev AI Language Identification Job

        ***

        Note: properties are not displayed in the returned object if they are
        null
      allOf:
        - $ref: '#/components/schemas/BaseAudioAnalysisJob'
        - type: object
          properties:
            type:
              type: string
              description: The type of action performed, in this case `language_id`
              enum:
                - language_id
              nullable: false
              default: language_id
              example: language_id
            processed_duration_seconds:
              type: number
              format: double
              description: >-
                Duration of the processed audio in seconds. Null if the job has
                not completed
              nullable: true
              example: 107
      example: $ref:'#/examples/NewLanguageIdentificationJob'
    BaseProblemDetails:
      type: object
      description: Problem details object returned on errors
      properties:
        title:
          type: string
          description: Short, human-readable summary of the problem type
        type:
          type: string
          description: URI that identifies the problem
        status:
          type: integer
          description: HTTP status code of the error
    BadRequestProblemDetails:
      allOf:
        - $ref: '#/components/schemas/BaseProblemDetails'
        - type: object
          properties:
            parameters:
              description: >-
                Invalid properties object where each property is the key, mapped
                to a list of reasons why the property is invalid
              type: object
              additionalProperties: true
    NotificationConfig:
      type: object
      nullable: true
      description: >
        Optional configuration for a callback url to invoke when processing is
        complete, in addition to auth

        headers if they are needed to invoke the callback url.

        Cannot be set if `callback_url` is set.

        This option will not be visible in the submission response.
      required:
        - url
      properties:
        url:
          type: string
          description: Optional callback url to invoke when processing is complete
          maxLength: 2048
          example: https://www.example.com/callback
        auth_headers:
          description: >-
            Optional authorization headers, if they are needed to invoke the
            callback. There are a few constraints: 1) the “Authorization” header
            is the only header that can be passed in, and 2) the header value
            must be of the form `<scheme> <token>`. For example:
            `{"Authorization": "Bearer $BEARER_TOKEN"}`
          type: object
          nullable: true
          properties:
            Authorization:
              type: string
              example: Bearer <token>
          required:
            - Authorization
          maxLength: 1000
    BaseSubmitJobOptions:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataField'
        callback_url:
          $ref: '#/components/schemas/CallbackUrlField'
        notification_config:
          $ref: '#/components/schemas/NotificationConfig'
        delete_after_seconds:
          $ref: '#/components/schemas/DeleteAfterSecondsField'
    SourceConfig:
      description: >
        Optional authorization headers, if they are needed to access the
        resource at the URL. Headers could be
         a single `Authorization` header of the form `<scheme> <token>`, and one of the [AWS signature v4 headers](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html).
        Only one of `source_config` and `media_url` may be set.

        This option will not be visible in the submission response.
      nullable: true
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: Direct download media url. Ignored if submitting job from file.
          maxLength: 2048
          example: https://www.rev.ai/FTC_Sample_1.mp3
        auth_headers:
          description: >-
            Optional authorization headers, if they are needed to access the
            resource at the media url. There are a few constraints: 1) the
            “Authorization” header is the only header that can be passed in, and
            2) the header value must be of the form `<scheme> <token>`. For
            example: `{"Authorization": "Bearer $BEARER_TOKEN"}`
          type: object
          nullable: true
          properties:
            Authorization:
              type: string
              example: Bearer <token>
          required:
            - Authorization
          maxLength: 1000
    BaseAudioAnalysisSubmitJobOptions:
      allOf:
        - $ref: '#/components/schemas/BaseSubmitJobOptions'
        - type: object
          properties:
            source_config:
              $ref: '#/components/schemas/SourceConfig'
            media_url:
              $ref: '#/components/schemas/AudioAnalysisMediaUrlField'
    SubmitLanguageIdentificationJobOptions:
      allOf:
        - $ref: '#/components/schemas/BaseAudioAnalysisSubmitJobOptions'
    SubmitLanguageIdentificationJobMultipartOptions:
      allOf:
        - $ref: '#/components/schemas/BaseSubmitJobOptions'
    InvalidStateDetails:
      allOf:
        - $ref: '#/components/schemas/BaseProblemDetails'
        - type: object
          properties:
            current_value:
              type: string
              description: Value passed in given request
            allowed_values:
              type: array
              description: Allowed values for this request
              items:
                type: string
            detail:
              type: string
              description: >-
                Human-readable explanation specific to this occurrence of the
                problem
    SupportedLanguages:
      type: string
      enum:
        - ar
        - cmn
        - cs
        - de
        - el
        - en
        - es
        - fi
        - fr
        - hu
        - it
        - ja
        - lt
        - lv
        - nl
        - pl
        - pt
        - ro
        - ru
        - sl
        - sv
        - tr
      x-enumDescriptions:
        ar: Arabic
        cmn: Mandarin
        cs: Czech
        de: German
        el: Greek
        en: English
        es: Spanish
        fi: Finnish
        fr: French
        hu: Hungarian
        it: Italian
        ja: Japanese
        lt: Lithuanian
        lv: Latvian
        nl: Dutch
        pl: Polish
        pt: Portuguese
        ro: Romanian
        ru: Russian
        sl: Slovenian
        sv: Swedish
        tr: Turkish
    LanguageIdentificationResult:
      description: Rev AI Language Identification Result Model
      type: object
      properties:
        top_language:
          allOf:
            - $ref: '#/components/schemas/SupportedLanguages'
            - type: object
              description: The most probable language of the audio, in ISO 639
        language_confidences:
          type: array
          items:
            type: object
            properties:
              language:
                allOf:
                  - $ref: '#/components/schemas/SupportedLanguages'
                  - type: object
                    description: The probable language of the audio, in ISO 639
              confidence:
                type: number
                minimum: 0
                maximum: 1
                description: |
                  Confidence score of the possible predicted language
  examples:
    BadLimitResponse:
      value:
        parameters:
          limit:
            - The max value for limit is 1000
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    InvalidStartingAfterResponse:
      value:
        parameters:
          starting_after:
            - Invalid job ID
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    NewLanguageIdentificationJob:
      value:
        id: Umx5c6F7pH7r
        status: in_progress
        created_on: '2018-05-05T23:23:22.29Z'
        type: language_id
    BadRequestNoInputMediaUrl:
      value:
        parameters:
          media_url:
            - One of media_url or source_config must be set
        type: https://www.rev.ai/api/v1/errors/invalid-parameters
        title: Your request parameters didn't validate
        status: 400
    CompletedLanguageIdentificationJob:
      value:
        id: Umx5c6F7pH7r
        status: completed
        created_on: '2018-05-05T23:23:22.29Z'
        completed_on: '2018-05-05T23:45:13.41Z'
        type: language_id
        processed_duration_seconds: 107.07
    FailedLanguageIdentificationJob:
      value:
        id: Umx5c6F7pH7r
        status: failed
        created_on: '2018-05-05T23:23:22.29Z'
        completed_on: '2018-05-05T23:23:24.11Z'
        failure: internal_processing
        failure_detail: Internal processing failed
        type: language_id
    ConflictAudioAnalysisJob_InvalidDeleteState:
      value:
        allowed_values:
          - completed
          - failed
        current_value: in_progress
        type: https://rev.ai/api/v1/errors/invalid-job-state
        title: Job is in invalid state
        detail: Job is in invalid state to be deleted
        status: 409
    ConflictAudioAnalysisJob_InvalidStateInProgress:
      value:
        allowed_values:
          - completed
        current_value: in_progress
        type: https://rev.ai/api/v1/errors/invalid-job-state
        title: Job is in invalid state
        detail: Job is in invalid state to obtain the output
        status: 409
    ConflictAudioAnalysisJob_InvalidStateFailed:
      value:
        allowed_values:
          - completed
        current_value: failed
        type: https://rev.ai/api/v1/errors/invalid-job-state
        title: Job is in invalid state
        detail: Job is in invalid state to obtain the output
        status: 409
  responses:
    Unauthorized:
      description: |
        Request Unauthorized
      content:
        application/problem+json:
          schema:
            properties:
              title:
                type: string
                description: Short, human-readable summary of the problem type
              status:
                type: integer
                description: HTTP status code of the error
          example:
            title: Authorization has been denied for this request
            status: 401
    ForbiddenDeployment:
      description: User does not have permission to access this deployment
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          example:
            type: https://www.rev.ai/api/v1/errors/access-denied
            title: >-
              Permisson has been denied for this request - access to this
              deployment is not allowed
            status: 403
    JobNotFound:
      description: Job Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          example:
            type: https://www.rev.ai/api/v1/errors/job-not-found
            title: could not find job
            status: 404
    HipaaForbiddenOrForbiddenDeployment:
      description: >-
        Request forbidden or user does not have permission to access this
        deployment
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BaseProblemDetails'
          examples:
            HIPAA forbidden:
              value:
                type: https://www.rev.ai/api/v1/errors/access-denied
                title: HIPAA user is not allowed to use media_url
                status: 403
            Forbidden deployment:
              value:
                type: https://www.rev.ai/api/v1/errors/access-denied
                title: >-
                  Permisson has been denied for this request - access to this
                  deployment is not allowed
                status: 403
    PayloadTooLarge:
      description: |
        Payload Too Large
      content:
        application/problem+json:
          schema:
            properties:
              title:
                type: string
                description: Short, human-readable summary of the problem type
              detail:
                type: string
                description: >-
                  Human-readable explanation specific to this occurrence of the
                  problem
              status:
                type: integer
                description: HTTP status code of the error
          example:
            title: Payload Too Large
            detail: Submitted payload exceeds maximum allowed file size
            status: 413
    DeleteJobSuccessful:
      description: |
        Job was successfully deleted
      content: {}
    SampleLanguageIdentificationResult:
      description: |
        Rev AI API Language Identification Result
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LanguageIdentificationResult'
          example:
            top_language: en
            language_confidences:
              - language: en
                confidence: 0.907
              - language: nl
                confidence: 0.023
              - language: ar
                confidence: 0.023
              - language: de
                confidence: 0.023
              - language: cmn
                confidence: 0.023
