Hamad Bin Khalifa University Translations API

openapi: 3.2.0
info:
  title: Fanar Translations API
  description: 'You can interact with FanarAPI for seamless chat completion and text processing using Fanar.

    Base URL: https://api.fanar.qa

    Request API Access: https://api.fanar.qa/request

    Models and release history: https://fanar.qa/en/models

    Rate Limits


    To ensure fair usage and optimal performance for all users, our API has rate limits in place. When you exceed a rate limit, your request will typically receive a 429 Too Many Requests HTTP status code.


    Limits by model


    These are our default settings for all models. We understand that your needs may vary. If your application requires higher throughput or more tailored rate limits for specific models, please contact us:


    Model

    Rate Limit


    Fanar

    50 requests/minute


    Fanar-S-1-7B

    50 requests/minute


    Fanar-C-1-8.7B

    50 requests/minute


    Fanar-C-2-27B

    50 requests/minute


    Fanar-2.0-Tools

    50 requests/minute


    Fanar-Sadiq

    50 requests/minute


    Fanar-Sadiq-2

    50 requests/minute


    Fanar-Sadiq-2 (validate)

    200 requests/minute


    Fanar-Sadiq-2 (deep research)

    20 requests/day


    Fanar-Sadiq-TTS-1

    20 requests/day


    Fanar-Oryx-IVU-2

    20 requests/day


    Fanar-Aura-TTS-2

    20 requests/day


    Fanar-Aura-STT-1

    20 requests/day


    Fanar-Aura-STT-LF-1

    10 requests/day


    Fanar-3.0-Aura-Transcribe (live stream sessions)

    20 requests/day


    Fanar-Oryx-IG-2

    20 requests/day


    Fanar-Guard-2

    50 requests/minute


    Fanar-Shaheen-MT-1

    20 requests/day


    Fanar-3.0-Shaheen-Translate

    20 requests/day


    Fanar-Diwan

    50 requests/minute


    Response headers


    Every rate-limited response reports your current quota, so you can back off before being throttled:


    Header

    Description


    x-ratelimit-limitRequests allowed per window.


    x-ratelimit-remainingRequests still available in the current window.


    x-ratelimit-resetSeconds until a request slot frees up.


    ratelimit-policyThe quota and its window in seconds, as limit;w=seconds — so 100;w=86400 means 100 requests per day.


    retry-afterSeconds to wait before retrying, sent only on a 429. When your own quota ran out it counts down to a free slot; when an upstream service throttled the request it carries that service''s own hint instead.


    Because x-ratelimit-limit alone cannot tell 3 per minute from 3 per day, read ratelimit-policy when you need the window. These headers are omitted for API keys with unlimited quota.'
  termsOfService: https://api.fanar.qa/terms-of-service
  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-3.0-Shaheen-Translate\",\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-3.0-Shaheen-Translate\",\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:
    TranslationModels:
      type: string
      enum:
      - Fanar-Shaheen-MT-1
      - Fanar-3.0-Shaheen-Translate
      title: TranslationModels
    ErrorStatus:
      type: integer
      enum:
      - 400
      - 401
      - 403
      - 429
      - 429
      - 500
      - 503
      - 504
      - 413
      - 422
      - 409
      - 404
      - 410
      - 499
      title: ErrorStatus
    ErrorContentFilterType:
      type: string
      enum:
      - safety
      - blocklist
      - incomplete
      title: ErrorContentFilterType
    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
    TranslationLangPairs:
      type: string
      enum:
      - en-ar
      - ar-en
      title: TranslationLangPairs
    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
    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-3.0-Shaheen-Translate
        text: Hello, how are you?
        langpair: en-ar
    TranslationPreprocessing:
      type: string
      enum:
      - default
      - preserve_html
      - preserve_whitespace
      - preserve_whitespace_and_html
      title: TranslationPreprocessing
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Provide your API key in the Authorization header using the Bearer scheme.