openapi: 3.2.0
info:
  title: Fanar Translations API
  description: You can interact with FanarAPI for seamless chat completion and text processing using Fanar.
  termsOfService: https://fanar.qa/terms-of-services
  contact:
    name: Fanar Support
    url: https://fanar.qa/
    email: support@fanar.qa
  version: 1.0.0
  x-logo:
    url: /static/white-logo.svg
    alt: logo
security:
- Bearer: []
tags:
- name: Translations
paths:
  /v1/translations:
    post:
      tags:
      - Translations
      summary: Translate
      description: Translate the given text into the specified language.
      operationId: translate_v1_translations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponse'
        '400':
          description: The content was filtered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: content_filter
                  message: The content was filtered
                  status: 400
                  param: prompt
                  type: safety
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: invalid_authentication
                  message: Invalid authentication
                  status: 401
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: invalid_authorization
                  message: Invalid authorization
                  status: 403
        '429':
          description: Rate limit reached or Exceeded quota
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: exceeded_quota
                  message: Exceeded quota
                  status: 429
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: internal_server_error
                  message: Internal server error
                  status: 500
        '503':
          description: Service overloaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: overloaded
                  message: Service overloaded
                  status: 503
        '504':
          description: Request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: timeout
                  message: Request timed out
                  status: 504
        '413':
          description: Request entity too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: too_large
                  message: Request entity too large
                  status: 413
        '422':
          description: Unprocessable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unprocessable
                  message: Unprocessable
                  status: 422
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: conflict
                  message: Conflict
                  status: 409
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: Not found
                  message: Not found
                  status: 404
        '410':
          description: No longer supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: no_longer_supported
                  message: No longer supported
                  status: 410
        '499':
          description: Client closed request before completion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: client_closed_request
                  message: Client closed request before completion
                  status: 499
      security:
      - Bearer: []
      x-codeSamples:
      - lang: Curl
        label: cURL
        source: "curl -X POST \"https://api.fanar.qa/v1/translations\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -d '{\n    \"model\": \"Fanar-Shaheen-MT-1\",\n    \"text\": \"Your text here\",\n    \"langpair\": \"ar-en\",\n    \"preprocessing\": \"default\"\n  }'\n"
      - lang: Python
        label: Python - requests
        source: "# Translation requires additional authorization and is not allowed by default.\n\nimport requests\n\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\",\n}\n\njson_data = {\n    \"model\": \"Fanar-Shaheen-MT-1\",\n    \"text\": \"مرحبا بك في عالم الذكاء الاصطناعي!\",\n    \"langpair\": \"ar-en\",\n    \"preprocessing\": \"default\",\n}\n\nresponse = requests.post(\"https://api.fanar.qa/v1/translations\", headers=headers, json=json_data)\n\nprint(response.json())"
components:
  schemas:
    ErrorCode:
      type: string
      enum:
      - content_filter
      - invalid_authentication
      - invalid_authorization
      - rate_limit_reached
      - exceeded_quota
      - internal_server_error
      - overloaded
      - timeout
      - too_large
      - unprocessable
      - conflict
      - Not found
      - no_longer_supported
      - client_closed_request
      title: ErrorCode
    TranslationModels:
      type: string
      enum:
      - Fanar-Shaheen-MT-1
      title: TranslationModels
    TranslationPreprocessing:
      type: string
      enum:
      - default
      - preserve_html
      - preserve_whitespace
      - preserve_whitespace_and_html
      title: TranslationPreprocessing
    TranslationLangPairs:
      type: string
      enum:
      - en-ar
      - ar-en
      title: TranslationLangPairs
    TranslationRequest:
      properties:
        model:
          $ref: '#/components/schemas/TranslationModels'
          description: The model to use for the translation.
        text:
          type: string
          title: Text
          description: The text to translate. It must not exceed 4,000 words.
        langpair:
          $ref: '#/components/schemas/TranslationLangPairs'
          description: 'The source-target language pair for translation, the current allowed possible values are:<br/>- <b>en-ar</b>: for English to Arabic<br/>- <b>ar-en</b>: for Arabic to English'
        preprocessing:
          anyOf:
          - $ref: '#/components/schemas/TranslationPreprocessing'
          - type: 'null'
          description: 'How to preprocess the text before translation:<br/>- <b>default</b>: Splits all sentences by natural punctuation (full stops, question marks, etc.), trims away extra whitespace, and removes HTML tags.<br/>- <b>preserve_html</b>: Does the same as “default”, but tries to preserve HTML tags.<br/>- <b>preserve_whitespace</b>: Aggressively tries to maintain all extra leading/trailing whitespaces and joins sentences across newlines to translate fixed-width content, for example.<br/>- <b>preserve_whitespace_and_html</b>: Combines the previous two.'
          default: default
      type: object
      required:
      - model
      - text
      - langpair
      title: TranslationRequest
      example:
        model: Fanar-Shaheen-MT-1
        text: Hello, how are you?
        langpair: en-ar
    TranslationResponse:
      properties:
        id:
          type: string
          title: Id
          description: A unique identifier for the translation.
        text:
          type: string
          title: Text
          description: The translated text
      type: object
      required:
      - id
      - text
      title: TranslationResponse
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          title: Message
          default: Internal server error
        status:
          $ref: '#/components/schemas/ErrorStatus'
          default: 500
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
        type:
          anyOf:
          - $ref: '#/components/schemas/ErrorContentFilterType'
          - type: 'null'
      type: object
      title: Error
    ErrorContentFilterType:
      type: string
      enum:
      - safety
      - blocklist
      - incomplete
      title: ErrorContentFilterType
    ErrorStatus:
      type: integer
      enum:
      - 400
      - 401
      - 403
      - 429
      - 429
      - 500
      - 503
      - 504
      - 413
      - 422
      - 409
      - 404
      - 410
      - 499
      title: ErrorStatus
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Provide your API key in the Authorization header using the Bearer scheme.