Emporix Text Generation API

openapi: 3.2.0
info:
  title: Emporix Text Generation API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged Text Generation across 2 of this provider''s published API definitions: emporix-ai-service-openapi.yml, emporix-ai-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
tags:
- name: Text Generation
  description: AI Text Generation
paths:
  /ai-service/{tenant}/texts:
    parameters:
    - name: tenant
      in: path
      required: true
      schema:
        type: string
      description: 'Your Emporix tenant name.


        **Note**: The tenant name should always be provided in lowercase.

        '
    post:
      summary: Generating text for an object description
      operationId: POST-ai-generate-description
      responses:
        '200':
          $ref: '#/components/responses/200_resp_GET_text_generation'
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
        '500':
          $ref: '#/components/responses/500_resp_common'
      description: 'Generates a text based on a prompt.

        Currently, the supported AI engine for the text generation is https://platform.openai.com/.


        ***

        Prerequisite: Using the AI service requires an API token, you have to either configure your own OpenAI account, or use the Emporix one. To configure your own OpenAI token, use the configuration service by storing the token under `openAiApiToken` key.


        If you don''t provide your own OpenAI token, the Emporix one is used with the following limits: 3 mln input tokens and 1 mln output tokens. When you reach the limit, the next requests are rejected and you have to provide your own OpenAI token.

        Emporix uses the gpt-4o-mini model by default.

        If you want to use your own OpenAI account with a different AI model please contact our Emporix Support Team to negotiate the model and usage.'
      security:
      - OAuth2:
        - ai.text_manage
      requestBody:
        $ref: '#/components/requestBodies/TextGeneration'
      tags:
      - Text Generation
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
        type:
          type: string
        message:
          type: string
        moreInfo:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              type:
                type: string
              message:
                type: string
              moreInfo:
                type: string
      description: ''
    GenerationResponse:
      title: GenerationResponse
      type: object
      description: Object represents the text generation response.
      properties:
        id:
          type: string
          description: 'Identifier of the text generation request. The value is populated only if the ID was provided in the request. '
        result:
          type: string
          description: Text generation result.
    TextGenerationRequest:
      title: TextGenerationRequest
      type: object
      description: Represents a request body for a text generation operation.
      required:
      - prompt
      properties:
        id:
          type: string
          description: Identifier of the request. The value is not mandatory - if provided, the ID is returned in the text generation response.
        prompt:
          type: string
          description: A prompt to AI engine. A desired text content is generated based on the prompt.
        maxTokens:
          type: integer
          description: Maximum number of tokens that should be used during text generation. If not provided, then 4097 is used.
    ErrorMessageFault:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
            detail:
              type: object
              properties:
                errorcode:
                  type: string
  responses:
    403_resp_common:
      description: Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Access forbidden:
              value:
                code: 403
                status: Forbidden
                message: The access to the requested resource has been forbidden by the server.
    401_resp_common:
      description: The authorization token is invalid or has expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageFault'
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    400_resp_common:
      description: The request was syntactically incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Code must not be null:
              value:
                code: 400
                status: Bad Request
                message: Validation problem with request body.
                details:
                - message: code must not be null nor blank
    500_resp_common:
      description: A server-side error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Internal Server Error:
              value:
                code: 500
                status: Internal Server Error
                message: Problem encountered while trying to connect to the database.
    200_resp_GET_text_generation:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerationResponse'
          examples:
            Text Generation Response:
              value:
                id: en
                result: Mini pipe cutters are small cutting tools that are designed to precisely and effectively cut through pipes ranging in size from 3 to 16 millimeters. Unlike some larger pipe cutters, these mini versions are conveniently small and light enough to be carried around easily and used in places where a standard-sized cutter may not be able to fit. They are typically made of hardened steel and are designed to work on most types of tubing and thin-walled plastic piping. The continuous interlocking jaws hold the pipe securely while the cutting blade smoothly and accurately creates a precise and neat cutting edge. Mini pipe cutters are the perfect tool for plumbers and those tackling smaller scale pipe work in hard-to-reach places.
  requestBodies:
    TextGeneration:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TextGenerationRequest'
          examples:
            Text generation request:
              value:
                id: en
                prompt: 'Generate a long description for product ''pipe cutter'' in language EN '
                maxTokens: 2048
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            ai.text_manage: Needed to execute actions related to the text generation.
            ai.completion_manage: Needed to execute actions related to the AI completions.
            ai.agentexecution_manage: Needed to execute agentic chat.
            ai.agentexecution_manage_own: Needed to execute agentic chat by customers.
            ai.agent_read: Needed to read AI agents.
            ai.agent_manage: Needed to manage AI agents.
          tokenUrl: https://api.emporix.io/oauth/token
x-refined-from:
- emporix-ai-service-openapi.yml
- emporix-ai-service-openapi.yml