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:
    ChatResponseTopLogprob:
      type: object
      required:
      - token
      - logprob
      - bytes
      properties:
        token:
          description: The token.
          type: string
        logprob:
          description: The log probability of the token.
          type: number
        bytes:
          description: A list of integers representing the UTF-8 bytes representation of the token.
          type: array
          items:
            type: integer
    FunctionObject:
      type: object
      properties:
        description:
          type: string
          description: 'A description of what the function does, used by the model to choose when and how to call the

            function.

            '
        name:
          type: string
          description: 'The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes,

            with a maximum length of 64.

            '
        parameters:
          $ref: '#/components/schemas/FunctionParameters'
        strict:
          type: boolean
          nullable: 'true'
          default: 'false'
          description: 'Whether to enable strict schema adherence when generating the function call. If set to true, the

            model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema

            is supported when `strict` is `true`. Learn more about Structured Outputs in [our

            docs](https://docs.aleph-alpha.com/products/pharia-ai/pharia-os/references/inference/structured-output/).

            '
      required:
      - name
    SteeringConceptRef:
      oneOf:
      - $ref: '#/components/schemas/WorkerSteeringConcept'
      - $ref: '#/components/schemas/SteeringConceptId'
    ChatRequestTool:
      type: object
      title: Function tool
      description: 'A function tool that can be used to generate a response.

        '
      properties:
        type:
          type: string
          enum:
          - function
          description: The type of the tool. Currently, only `function` is supported.
        function:
          $ref: '#/components/schemas/FunctionObject'
      required:
      - type
      - function
    EmbeddingV2ResponseData:
      type: object
      properties:
        object:
          type: string
          enum:
          - embedding
          description: The object type, which is always "embedding".
        embedding:
          oneOf:
          - type: array
            items:
              type: number
              format: float
            title: Embedding (float)
            description: The embedding vector as an array of floats.
          - type: string
            title: Embedding (base64)
            description: The embedding vector as a base64-encoded numpy array.
          description: The embedding vector, which is a list of floats or a base64-encoded numpy array depending on the encoding_format parameter.
        index:
          type: integer
          description: The index of the embedding in the list of embeddings.
      required:
      - object
      - embedding
      - index
    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
    MultimodalPrompt:
      title: Multimodal
      type: array
      description: An array of prompt items for multimodal request. Can support any combination of text, images, and token ids.
      items:
        oneOf:
        - $ref: '#/components/schemas/TextPromptItem'
        - $ref: '#/components/schemas/ImagePromptItem'
        - $ref: '#/components/schemas/TokenIdsPromptItem'
    TextPromptItemImportance:
      type: object
      description: 'Explains the importance of a text prompt item.

        The amount of items in the "scores" array depends on the granularity setting.

        Each score object contains an inclusive start character and a length of the substring plus

        a floating point score value.

        '
      properties:
        type:
          type: string
          enum:
          - text
        scores:
          type: array
          items:
            type: object
            properties:
              start:
                type: integer
              length:
                type: integer
              score:
                type: number
    RerankRequest:
      type: object
      example:
        model: your-reranker-model
        query: What is the capital of France?
        documents:
        - The capital of Brazil is Brasilia.
        - The capital of France is Paris.
        - Horses and cows are both animals.
        top_n: '2'
      properties:
        query:
          type: string
          description: The query to rerank the documents against.
        documents:
          type: array
          items:
            type: string
          description: The list of documents to rerank.
        top_n:
          nullable: 'true'
          type: integer
          description: The number of documents to return. Defaults to the number of documents if not provided.
      required:
      - query
      - documents
    TargetItemImportance:
      type: object
      description: 'Explains the importance of text in the target string that came before the currently

        to-be-explained target token. The amount of items in the "scores" array depends on the

        granularity setting.

        Each score object contains an inclusive start character and a length of the substring plus

        a floating point score value.

        '
      properties:
        type:
          type: string
          enum:
          - target
        scores:
          type: array
          items:
            type: object
            properties:
              start:
                type: integer
              length:
                type: integer
              score:
                type: number
    TranslationRequest:
      type: object
      example:
        model: pharia-1-mt-translation
        source: What is your name?
        target_language: de
      properties:
        model:
          type: string
          description: The name of the model to be used for the translation.
        source:
          type: string
          description: The input text to be translated.
        target_language:
          type: string
          description: 'The desired target language into which the input text should be translated. The language

            must be specified using ISO 639 (and RFC 1766) language codes such as "en" for English,

            "de" for German, "fr" for French, etc. For a list of supported languages, refer to the

            `/languages` endpoint.

            '
      required:
      - model
      - source
      - target_language
    Prompt:
      description: "This field is used to send prompts to the model.\nA prompt can either be a text prompt or a multimodal prompt.\nA text prompt is a string of text.\nA multimodal prompt is an array of prompt items. It can be a combination of text,\nimages, and token ID arrays.\n\nIn the case of a multimodal prompt, the prompt items will be concatenated and a single\nprompt will be used for the model.\n\nTokenization:\n  - Token ID arrays are used as as-is.\n  - Text prompt items are tokenized using the tokenizers specific to the model.\n  - Each image is converted into 144 tokens.\n"
      oneOf:
      - title: Text Prompt
        type: string
        description: The text to be completed. Unconditional completion can be started with an empty string (default). The prompt may contain a zero shot or few shot task.
      - $ref: '#/components/schemas/MultimodalPrompt'
    EmbeddingRequest:
      type: object
      example:
        model: pharia-1-embedding-4608-control
        prompt: An apple a day keeps the doctor away.
        layers:
        - '0'
        - '1'
        tokens: 'false'
        pooling:
        - max
        type: default
      properties:
        model:
          type: string
          description: Name of model to use. A model name refers to a model architecture (number of parameters among others). Always the latest version of model is used. The model output contains information as to the model version.
        hosting:
          $ref: '#/components/schemas/Hosting'
        prompt:
          $ref: '#/components/schemas/Prompt'
        layers:
          type: array
          items:
            type: integer
          description: "A list of layer indices from which to return embeddings.\n\n    - Index 0 corresponds to the word embeddings used as input to the first transformer layer\n\n    - Index 1 corresponds to the hidden state as output by the first transformer layer, index 2 to the output of the second layer etc.\n\n    - Index -1 corresponds to the last transformer layer (not the language modelling head), index -2 to the second last\n"
        tokens:
          type: boolean
          nullable: 'true'
          description: Flag indicating whether the tokenized prompt is to be returned (True) or not (False)
        pooling:
          type: array
          items:
            type: string
          description: "Pooling operation to use. Pooling operations include:\n\n    - mean: Aggregate token embeddings across the sequence dimension using an average.\n\n    - weighted_mean: Position weighted mean across sequence dimension with latter tokens having a higher weight.\n\n    - max: Aggregate token embeddings across the sequence dimension using a maximum.\n\n    - last_token: Use the last token.\n\n    - abs_max: Aggregate token embeddings across the sequence dimension using a maximum of absolute values.\n"
        type:
          type: string
          nullable: 'true'
          description: 'Explicitly set embedding type to be passed to the model. This parameter was created to allow for semantic_embed embeddings and will be deprecated. Please use the semantic_embed-endpoint instead.

            '
        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:
      - model
      - prompt
    RecentRequestsResponse:
      type: array
      items:
        type: object
        properties:
          create_timestamp:
            type: string
          model_name:
            type: string
          request_type:
            type: string
          token_count_prompt:
            type: integer
          image_count_prompt:
            type: integer
          token_count_completion:
            type: integer
          duration_millis:
            type: integer
          credits:
            type: number
    FunctionParameters:
      type: object
      description: 'The parameters the functions accepts, described as a JSON Schema object. Omitting `parameters`

        defines a function with an empty parameter list.

        '
      additionalProperties: 'true'
    CompletionSummary:
      description: Response object being returned once per completion request after all streams have finished.
      type: object
      example:
        type: completion_summary
        num_tokens_prompt_total: '4'
        num_tokens_generated: '5'
      required:
      - type
      - num_tokens_prompt_total
      - num_tokens_generated
      properties:
        type:
          description: Marker tag denoting the type of the stream item. Will always be `completion_summary` for `CompletionSummary`s.
          type: string
          enum:
          - completion_summary
        optimized_prompt:
          $ref: '#/components/schemas/OptimizedPrompt'
        num_tokens_prompt_total:
          description: "Number of tokens combined across all completion tasks.\n\nIn particular, if you set best_of or n to a number larger than 1 then we report the\ncombined prompt token count for all best_of or n tasks.\n\nTokenization:\n  - Token ID arrays are used as as-is.\n  - Text prompt items are tokenized using the tokenizers specific to the model.\n  - Each image is converted into a fixed amount of tokens that depends on the chosen model.\n"
          type: integer
        num_tokens_generated:
          description: 'Number of tokens combined across all completion tasks.

            If multiple completions are returned or best_of is set to a value greater than 1 then

            this value contains the combined generated token count.    ChatRequest:

            '
          type: integer
    ChatRequestMessageToolCall:
      type: object
      title: Function tool call
      description: 'A call to a function tool created by the model.

        '
      properties:
        id:
          type: string
          description: The ID of the tool call.
        type:
          type: string
          enum:
          - function
          description: The type of the tool.
        function:
          type: object
          description: The function that the model called.
          properties:
            name:
              type: string
              description: The name of the functio

# --- 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