Aleph Alpha Tasks API

openapi: 3.2.0
info:
  title: Aleph Alpha Tasks API
  version: 4.7.0
  description: Access and interact with Aleph Alpha models and functionality over HTTP endpoints.
  contact:
    email: support@aleph-alpha.com
servers:
- url: '{host}/v1'
  variables:
    host:
      default: https://api.pharia.example.com
tags:
- name: tasks
  description: Requests for different types of tasks you can request with our models.
paths:
  /complete:
    post:
      summary: Completion
      description: 'Will complete a prompt using a specific model. To obtain a valid model, use `GET` `/model-settings`.

        '
      operationId: complete
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CompletionResponse'
                - $ref: '#/components/schemas/StreamChunk'
                - $ref: '#/components/schemas/StreamSummary'
                - $ref: '#/components/schemas/CompletionSummary'
  /complete/json:
    post:
      summary: JSON Completion
      description: 'In contrast to the `/complete` endpoint, the model generates a completion in valid JSON format, even if not requested explicitly in the prompt.

        Note: If the max_tokens, i.e., the maximum number of allowed completion tokens is encountered before the completion is finished by the model,

        then the JSON output will be cut off and therefore invalid.


        JSON completion is currently only available for luminous workers.


        To obtain a valid model, use `GET /models_available`.

        '
      operationId: completeJson
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
  /chat/completions:
    post:
      operationId: chatCompletions
      summary: Chat
      description: Retrieves one or multiple chat completions for a given prompt
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatResponse'
  /embeddings:
    post:
      summary: Embeddings
      description: 'Creates embeddings from text input. This follows industry standard embedding endpoints

        (e.g. OpenAI) and provides vector representations that can be used for semantic similarity,

        search, clustering, recommendations, anomaly detection, and classification tasks.

        To ensure deployed embedding models support this endpoint, they need to be configured with

        `embedding_task.supported = true` in the model settings.

        '
      operationId: embeddings
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingV2Request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingV2Response'
  /semantic_embed:
    post:
      summary: Semantic Embeddings
      description: Embeds a prompt using a specific model and semantic embedding method. Resulting vectors that can be used for downstream tasks (e.g. semantic similarity) and models (e.g. classifiers). To obtain a valid model, use `GET` `/model-settings`.
      operationId: semanticEmbed
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SemanticEmbeddingRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticEmbeddingResponse'
  /batch_semantic_embed:
    post:
      summary: Batched Semantic Embeddings
      description: Embeds multiple prompts using a specific model and semantic embedding method. Resulting vectors that can be used for downstream tasks (e.g. semantic similarity) and models (e.g. classifiers). To obtain a valid model, use `GET` `/model-settings`.
      operationId: batchSemanticEmbed
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSemanticEmbeddingRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSemanticEmbeddingResponse'
  /instructable_embed:
    post:
      summary: Semantic Embeddings with instructions
      description: Embeds the input using an instruction and a specific model. Resulting vectors that can be used for downstream tasks (e.g. semantic similarity) and models (e.g. classifiers). To obtain a valid model, use `GET` `/model-settings`.
      operationId: instructableEmbed
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstructableEmbeddingRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticEmbeddingResponse'
  /embed:
    post:
      summary: Embeddings (Deprecated)
      deprecated: 'true'
      description: Embeds a text using a specific model. Resulting vectors that can be used for downstream tasks (e.g. semantic similarity) and models (e.g. classifiers). To obtain a valid model, use `GET` `/model-settings`.
      operationId: embed
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
  /evaluate:
    post:
      summary: Evaluate
      description: Evaluates the model's likelihood to produce a completion given a prompt.
      operationId: evaluate
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationResponse'
  /explain:
    post:
      operationId: explain
      summary: Explanation
      description: 'Better understand the source of a completion, specifically on how much each section of a

        prompt impacts each token of the completion.

        '
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExplanationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplanationResponse'
  /tokenize:
    post:
      summary: Tokenize
      description: Tokenize a prompt for a specific model. To obtain a valid model, use `GET` `/model-settings`.
      operationId: tokenize
      tags:
      - tasks
      security:
      - token: []
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenizationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenizationResponse'
  /detokenize:
    post:
      summary: Detokenize
      description: Detokenize a list of tokens into a string. To obtain a valid model, use `GET` `/model-settings`.
      operationId: detokenize
      tags:
      - tasks
      security:
      - token: []
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetokenizationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetokenizationResponse'
  /users/me/requests:
    get:
      summary: Query Recent Usage (Deprecated)
      deprecated: 'true'
      description: 'A list of the ten most recent tasks successfully completed by the API. Contains statistics

        about the task, including duration of execution and cost in credits.

        '
      operationId: recentRequests
      tags:
      - tasks
      security:
      - token: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentRequestsResponse'
  /transcribe:
    post:
      summary: Transcribe audio
      description: Transcribes an audio file using a specified transcription model
      operationId: transcribe
      tags:
      - tasks
      security:
      - token: []
      requestBody:
        required: 'true'
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TranscribeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscribeResponse'
  /translate:
    post:
      summary: Translation
      description: 'Translates input text from one to another specified target language

        '
      operationId: translate
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TranslationResponse'
  /rerank:
    post:
      summary: Rerank
      description: 'This endpoint takes in a query and a list of documents and produces an array with each text assigned

        a relevance score. To claim that a deployed reranker model supports this endpoint, it needs to be

        configured with `rerank_task.supported = true` in the model settings.

        '
      operationId: rerank
      tags:
      - tasks
      security:
      - token: []
      parameters:
      - in: query
        name: nice
        schema:
          type: boolean
        description: 'Setting this to True, will signal to the API that you intend to be nice to other users

          by de-prioritizing your request below concurrent ones.

          '
      requestBody:
        required: 'true'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerankRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerankResponse'
components:
  schemas:
    TextPromptItem:
      type: object
      title: Text
      required:
      - type
      - data
      properties:
        type:
          type: string
          enum:
          - text
        data:
          type: string
        controls:
          type: array
          items:
            type: object
            required:
            - start
            - length
            - factor
            properties:
              start:
                type: integer
                description: Starting character index to apply the factor to.
              length:
                type: integer
                description: The amount of characters to apply the factor to.
              factor:
                type: number
                description: 'Factor to apply to the given token in the attention matrix.


                  - 0 <= factor < 1 => Suppress the given token

                  - factor == 1 => identity operation, no change to attention

                  - factor > 1 => Amplify the given token

                  '
              token_overlap:
                type: string
                enum:
                - partial
                - complete
                default: partial
                description: 'What to do if a control partially overlaps with a text token.


                  If set to "partial", the factor will be adjusted proportionally with the amount

                  of the token it overlaps. So a factor of 2.0 of a control that only covers 2 of

                  4 token characters, would be adjusted to 1.5. (It always moves closer to 1, since

                  1 is an identity operation for control factors.)


                  If set to "complete", the full factor will be applied as long as the control

                  overlaps with the token at all.

                  '
    DetokenizationRequest:
      type: object
      example:
        model: llama-3.1-8b-instruct
        token_ids:
        - '560'
        - '34438'
        - '246'
        - '1966'
        - '18075'
        - '275'
        - '8809'
        - '3476'
        - '17'
      properties:
        model:
          type: string
        token_ids:
          type: array
          items:
            type: integer
      required:
      - model
      - token_ids
    SemanticEmbeddingRequest:
      type: object
      example:
        model: llama-3.1-8b-instruct
        prompt: An apple a day keeps the doctor away.
        representation: symmetric
        compress_to_size: '128'
      properties:
        model:
          type: string
          description: Name of the model to use. A model name refers to a model's architecture (number of parameters among others). The most recent version of the model is always used. The model output contains information as to the model version. To find out which models support semantic embeddings, please refer to the `/model-settings` endpoint.
        hosting:
          $ref: '#/components/schemas/Hosting'
        prompt:
          $ref: '#/components/schemas/Prompt'
        representation:
          type: string
          enum:
          - symmetric
          - document
          - query
          description: 'Type of embedding representation to embed the prompt with.


            `"symmetric"`: Symmetric embeddings assume that the text to be compared is interchangeable. Usage examples for symmetric embeddings are clustering, classification, anomaly detection or visualisation tasks. "symmetric" embeddings should be compared with other "symmetric" embeddings.


            `"document"` and `"query"`: Asymmetric embeddings assume that there is a difference between queries and documents. They are used together in use cases such as search where you want to compare shorter queries against larger documents.


            `"query"`-embeddings are optimized for shorter texts, such as questions or keywords.


            `"document"`-embeddings are optimized for larger pieces of text to compare queries against.

            '
        compress_to_size:
          $ref: '#/components/schemas/SemanticEmbeddingCompressToSize'
          nullable: 'true'
        normalize:
          type: boolean
          default: 'false'
          description: 'Return normalized embeddings. This can be used to save on additional compute when applying a cosine similarity metric.

            '
        contextual_control_threshold:
          type: number
          default: 'null'
          nullable: 'true'
          description: 'If set to `null`, attention control parameters only apply to those tokens that have

            explicitly been set in the request.

            If set to a non-null value, we apply the control parameters to similar tokens as well.

            Controls that have been applied to one token will then be applied to all other tokens

            that have at least the similarity score defined by this parameter.

            The similarity score is the cosine similarity of token embeddings.

            '
        control_log_additive:
          type: boolean
          default: 'true'
          description: '`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.

            `false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`

            '
      required:
      - prompt
      - representation
    BatchSemanticEmbeddingRequest:
      type: object
      example:
        model: pharia-1-embedding-4608-control
        prompts:
        - An apple a day keeps the doctor away.
        - A journey of thousand miles begins with a single step.
        representation: symmetric
        compress_to_size: '128'
      properties:
        model:
          type: string
          description: Name of the model to use. A model name refers to a model's architecture (number of parameters among others). The most recent version of the model is always used. The model output contains information as to the model version. To find out which models support semantic embeddings, please refer to the `/model-settings` endpoint.
        hosting:
          $ref: '#/components/schemas/Hosting'
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/Prompt'
        representation:
          type: string
          enum:
          - symmetric
          - document
          - query
          description: 'Type of embedding representation to embed the prompt with.


            `"symmetric"`: Symmetric embeddings assume that the text to be compared is interchangeable. Usage examples for symmetric embeddings are clustering, classification, anomaly detection or visualisation tasks. "symmetric" embeddings should be compared with other "symmetric" embeddings.


            `"document"` and `"query"`: Asymmetric embeddings assume that there is a difference between queries and documents. They are used together in use cases such as search where you want to compare shorter queries against larger documents.


            `"query"`-embeddings are optimized for shorter texts, such as questions or keywords.


            `"document"`-embeddings are optimized for larger pieces of text to compare queries against.

            '
        compress_to_size:
          $ref: '#/components/schemas/SemanticEmbeddingCompressToSize'
          nullable: 'true'
        normalize:
          type: boolean
          default: 'false'
          description: 'Return normalized embeddings. This can be used to save on additional compute when applying a cosine similarity metric.

            '
        contextual_control_threshold:
          type: number
          default: 'null'
          nullable: 'true'
          description: 'If set to `null`, attention control parameters only apply to those tokens that have

            explicitly been set in the request.

            If set to a non-null value, we apply the control parameters to similar tokens as well.

            Controls that have been applied to one token will then be applied to all other tokens

            that have at least the similarity score defined by this parameter.

            The similarity score is the cosine similarity of token embeddings.

            '
        control_log_additive:
          type: boolean
          default: 'true'
          description: '`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.

            `false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`

            '
      required:
      - prompts
      - representation
    ChatRequest:
      type: object
      required:
      - messages
      - model
      example:
        model: llama-3.1-8b-instruct
        messages:
        - role: system
          content: You are a helpful assistant.
        - role: user
          content: Can you help me with my homework?
        - role: assistant
          content: Sure, what do you need help with?
        - role: user
          content: I need help with my math homework.
      properties:
        messages:
          description: A list of messages comprising the conversation so far.
          type: array
          items:
            $ref: '#/components/schemas/ChatRequestMessage'
        model:
          description: 'The ID of the model to query.


            The requested model must be eligible for chat completions.

            '
          type: string
        frequency_penalty:
          description: 'When specified, this number will decrease (or increase) the likelihood of repeating tokens that were mentioned prior in the completion.


            The penalty is cumulative. The more a token is mentioned in the completion, the more its probability will decrease.

            '
          type: number
          minimum: '-2'
          maximum: '2'
        logit_bias:
          description: 'When specified, the provided hash map will affect the likelihood of the specified token <u>IDs</u> (!) appearing in the completion.


            Mathematically, the bias is added to the logits generated by the model prior to sampling. Values between -1 and 1 should decrease or increase likelihood of selection while values like -100 or 100 should result in a ban or exclusive selection of the relevant token.


            Note that since JSON does not support integer keys, the token IDs are represented as strings.

            '
          additionalProperties:
            type: number
            minimum: '-100'
            maximum: '100'
        logprobs:
          description: When set to true, the model will return the log probabilities of the sampled tokens in the completion.
          type: boolean
        top_logprobs:
          description: When specified, the model will return the log probabilities of the top `n` tokens in the completion.
          type: integer
          minimum: '0'
          maximum: '20'
        max_tokens:
          description: 'The maximum number of tokens to generate in the completion. The model will stop generating tokens once it reaches this length.


            The maximum value for this parameter depends on the specific model and the length of the input prompt. When no value is provided, the highest possible value will be used.

            '
          type: integer
          minimum: '1'
        n:
          description: 'The number of completions to generate for each prompt. The model will generate this many completions and return all of them.


            When no value is provided, one completion will be returned.

            '
          type: integer
          minimum: '1'
        presence_penalty:
          description: 'When specified, this number will decrease (or increase) the likelihood of repeating tokens that were mentioned prior in the completion.s


            The penalty is not cumulative. Mentioning a token more than once will not increase the penalty further.

            '
          type: number
          minimum: '-2'
          maximum: '2'
        response_format:
          description: 'An object specifying the format that the model must output.

            The response format can be passed either directly in the http request,

            or via the Aleph Alpha Client using a pydantic or a JSONSchema object.

            Also compatible with the OpenAI client passing a pydantic object

            as response_format.

            '
          $ref: '#/components/schemas/ResponseFormat'
        seed:
          deprecated: 'true'
          description: This parameter is unsupported and will be ignored.
        service_tier:
          deprecated: 'true'
          description: This parameter is unsupported and will be ignored.
        stop:
          description: Optional. When specified, sequence generation will stop when the model generates the specified token or tokens.
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        stream:
          description: 'When set to true, the model will transmit all completions tokens as soon as they become available via the [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format) protocol.

            '
          type: boolean
        stream_options:
          description: Additional options to affect the streaming behavior.
          type: object
          properties:
            include_usage:
              description: 'If set, an additional chunk will be streamed before the `data: [DONE]` message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array.'
              type: boolean
        temperature:
          description: 'Controls the randomness of the model. Lower values will make the model more deterministic and higher values will make it more random.


            Mathematically, the temperature is used to divide the logits before sampling. A temperature of 0 will always return the most likely token.


            When no value is provided, the default value of 1 will be used.

            '
          type: number
          minimum: '0'
          maximum: '2'
        top_p:
          description: '"nucleus" parameter to dynamically adjust the number of choices for each predicted token based on the cumulative probabilities. It specifies a probability threshold, below which all less likely tokens are filtered out.


            When no value is provided, the default value of 1 will be used.

            '
          type: number
          minimum: '0'
          maximum: '1'
        steering_concepts:
          type: array
          items:
            $ref: '#/components/schemas/SteeringConceptRef'
          default: []
          description: 'Specifies how the output of the model should be steered. This steers

            the output in the direction given by positive examples associated to

            the steering concept and away from the negative examples.


            Currently only one steering concept at a time is supported.

            '
        tools:
          type: array
          description: 'A list of tools the model may call. Currently, only functions are supported as a tool. Use

            this to provide a list of functions the model may generate JSON inputs for. A max of 128

            functions are supported.

            '
          items:
            $ref: '#/components/schemas/ChatRequestTool'
        tool_choice:
          description: 'Controls which (if any) tool is called by the model.

            `none` means the model will not call any tool and instead generates a message.

            `auto` means the model can pick between generating a message or calling one or more tools.

            `required` means the model must call one or more tools.

            Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces

            the model to call that tool.

            `none` is the default when no tools are present. `auto` is the default if tools are present.

            '
          anyOf:
          - type: string
            description: '`none` means the model will not call any tool and instead generates a message. `auto` means the

              model can pick between generating a message or calling one or more tools. `required` means the

              model must call one or more tools.

              '
            enum:
            - none
            - auto
            - required
          - type: object
            title: Function tool choice
            description: Specifies a tool the model should use.
            properties:
              type:
                type: string
                enum:
                - function
                description: For function calling, the type is always `function`.
              function:
                type: object
                properties:
                  name:
                   

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aleph-alpha/refs/heads/main/openapi/aleph-alpha-tasks-api-openapi.yml