Yandex Translate API Translation API

openapi: 3.2.0
info:
  title: Yandex Translate Language Detection Translation API
  description: Yandex Translate is a machine translation REST API from Yandex Cloud that supports 100+ languages. It provides text translation between any supported language pair, automatic source language detection, and listing of all supported languages. The API uses neural machine translation technology and supports glossaries for domain-specific vocabulary.
  version: v2
  contact:
    url: https://yandex.cloud/en/docs/translate/
  license:
    name: Yandex Cloud Terms of Service
    url: https://yandex.cloud/en/legal/cloud_termsofuse/
servers:
- url: https://translate.api.cloud.yandex.net
  description: Yandex Cloud Translate API endpoint
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Translation
  description: Operations for translating text between languages
paths:
  /translate/v2/translate:
    post:
      operationId: translate
      summary: Translate text
      description: Translates the text to the specified language. Supports translating arrays of strings, auto-detection of source language, HTML format, and custom glossaries.
      tags:
      - Translation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateRequest'
            example:
              targetLanguageCode: en
              texts:
              - Привет, мир!
              - Как дела?
              folderId: b1gd3hm2nj34ibndf3sd
      responses:
        '200':
          description: Successful translation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateResponse'
              example:
                translations:
                - text: Hello, world!
                  detectedLanguageCode: ru
                - text: How are you?
                  detectedLanguageCode: ru
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TranslateRequest:
      type: object
      description: Request body for translating text
      required:
      - targetLanguageCode
      - texts
      properties:
        sourceLanguageCode:
          type: string
          maxLength: 3
          description: The language code of the source text. Most languages use ISO 639-1 format (e.g., 'ru'). Required when using a glossary.
          example: ru
        targetLanguageCode:
          type: string
          maxLength: 3
          description: The target language code to translate to. Most languages use ISO 639-1 format (e.g., 'en').
          example: en
        format:
          type: string
          description: Format of the text to be translated.
          enum:
          - FORMAT_UNSPECIFIED
          - PLAIN_TEXT
          - HTML
          default: PLAIN_TEXT
        texts:
          type: array
          description: Array of strings to translate. The maximum total length of all strings is 10000 characters.
          minItems: 1
          items:
            type: string
          example:
          - Привет, мир!
        folderId:
          type: string
          maxLength: 50
          description: ID of the folder to which you have access. Required for authorization with a user account. Do not specify if using a service account.
        model:
          type: string
          maxLength: 50
          description: Model ID if using a custom translation model.
        glossaryConfig:
          $ref: '#/components/schemas/TranslateGlossaryConfig'
        speller:
          type: boolean
          description: Enable spell checking for the source text.
          default: false
    TranslatedText:
      type: object
      description: A single translated text result
      properties:
        text:
          type: string
          description: The translated text.
          example: Hello, world!
        detectedLanguageCode:
          type: string
          description: The detected language code of the source text. Most languages use ISO 639-1 format (e.g., 'ru').
          example: ru
    GlossaryPair:
      type: object
      description: A source-to-translation pair for use in a glossary
      required:
      - sourceText
      - translatedText
      properties:
        sourceText:
          type: string
          description: Text in the source language.
        translatedText:
          type: string
          description: Text in the target language.
        exact:
          type: boolean
          description: Allows adding translations for specific terms to neuroglossaries, enabling exact matching of the source term.
          default: false
    TranslateResponse:
      type: object
      description: Response containing translated texts
      properties:
        translations:
          type: array
          description: Array of translated texts in the same order as the input texts.
          items:
            $ref: '#/components/schemas/TranslatedText'
    TranslateGlossaryConfig:
      type: object
      description: Configuration for applying a glossary during translation
      properties:
        glossaryData:
          $ref: '#/components/schemas/GlossaryData'
    ErrorResponse:
      type: object
      description: Error response from the API
      properties:
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: array
          description: Additional error details.
          items:
            type: object
    GlossaryData:
      type: object
      description: Inline glossary data with text pairs
      properties:
        glossaryPairs:
          type: array
          description: Array of text pairs defining source-to-translation mappings. Maximum total length of all source texts is 10000 characters. Maximum total length of all translated texts is 10000 characters.
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/GlossaryPair'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'IAM token obtained from Yandex Identity and Access Management (IAM). Pass as ''Authorization: Bearer <IAM_TOKEN>''.'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key for service accounts. Pass as ''Authorization: Api-Key <API_KEY>''.'
externalDocs:
  description: Yandex Translate API Reference
  url: https://yandex.cloud/en/docs/translate/api-ref/