Hamad Bin Khalifa University Poems API

openapi: 3.2.0
info:
  title: Fanar Poems 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: Poems
paths:
  /v1/poems/generations:
    post:
      tags:
      - Poems
      summary: Create Poem
      description: 'This endpoint is compatible with the OpenAI library.

        Creates a poem given a prompt.'
      operationId: create_poem_v1_poems_generations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PoemGenerationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoemGenerationResponse'
        '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/poems/generations\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -d '{\n    \"model\": \"Fanar-Diwan\",\n    \"prompt\": \"Your text here\"\n  }'\n"
      - lang: Python
        label: Python - requests
        source: "# Poem generation 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-Diwan\",\n    \"prompt\": \"Your text here\",\n}\n\nresponse = requests.post(\"https://api.fanar.qa/v1/poems/generations\", headers=headers, json=json_data)\n\nprint(response.json())"
components:
  schemas:
    PoemGenerationResponse:
      properties:
        id:
          type: string
          title: Id
          description: A unique identifier for the poem generation.
        poem:
          type: string
          title: Poem
          description: The generated poem.
      type: object
      required:
      - id
      - poem
      title: PoemGenerationResponse
    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
    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
    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
    PoemGenerationRequest:
      properties:
        model:
          $ref: '#/components/schemas/PoemGenerationModels'
          description: The model to use for the poem generation.
        prompt:
          type: string
          title: Prompt
          description: A text description of the desired poem.
      type: object
      required:
      - model
      - prompt
      title: PoemGenerationRequest
      example:
        model: Fanar-Diwan
        prompt: Write a poem about the sea
    PoemGenerationModels:
      type: string
      enum:
      - Fanar-Diwan
      title: PoemGenerationModels
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Provide your API key in the Authorization header using the Bearer scheme.