{ "openapi": "3.0.3", "info": { "title": "Aleph Alpha API", "version": "4.7.0", "description": "Access and interact with Aleph Alpha models and functionality over HTTP endpoints.", "contact": { "email": "support@aleph-alpha.com" } }, "components": { "securitySchemes": { "token": { "type": "http", "scheme": "bearer", "description": "Can be generated in your [Aleph Alpha profile](https://app.aleph-alpha.com/profile)" } }, "schemas": { "Hosting": { "type": "string", "nullable": "true", "enum": [ "aleph-alpha", "null" ], "description": "Optional parameter that specifies which datacenters may process the request.\nYou can either set the parameter to \"aleph-alpha\" or omit it (defaulting to `null`).\n\nNot setting this value, or setting it to `null`, gives us maximal flexibility in processing your request in our\nown datacenters and on servers hosted with other providers. Choose this option for maximum availability.\n\nSetting it to \"aleph-alpha\" allows us to only process the request in our own datacenters.\nChoose this option for maximal data privacy.\n" }, "ResponseFormat": { "type": "object", "description": "An object specifying the format that the model must output.\nSetting to `{ \"type\": \"json_schema\" }` enables structured output mode.\n", "required": [ "type", "json_schema" ], "properties": { "type": { "type": "string", "enum": [ "json_schema" ], "description": "The type of response format. Only \"json_schema\" is currently supported." }, "json_schema": { "type": "object", "description": "A JSON schema definition that the output must conform to.\nThis should follow the JSON Schema specification (https://json-schema.org/).\n", "required": [ "name", "schema" ], "properties": { "name": { "type": "string", "description": "The name of the JSON schema." }, "description": { "type": "string", "description": "A description of what the schema represents." }, "strict": { "type": "boolean", "description": "Whether to use strict mode for schema validation.", "default": "false" }, "schema": { "type": "object", "description": "A JSON Schema object defining the expected output structure.\nSupports standard JSON Schema properties like type, properties, required, etc.\n", "additionalProperties": "true" } } } } }, "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" } ] } }, "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.\n\n- 0 <= factor < 1 => Suppress the given token\n- factor == 1 => identity operation, no change to attention\n- factor > 1 => Amplify the given token\n" }, "token_overlap": { "type": "string", "enum": [ "partial", "complete" ], "default": "partial", "description": "What to do if a control partially overlaps with a text token.\n\nIf set to \"partial\", the factor will be adjusted proportionally with the amount\nof the token it overlaps. So a factor of 2.0 of a control that only covers 2 of\n4 token characters, would be adjusted to 1.5. (It always moves closer to 1, since\n1 is an identity operation for control factors.)\n\nIf set to \"complete\", the full factor will be applied as long as the control\noverlaps with the token at all.\n" } } } } } }, "ImagePromptItem": { "type": "object", "title": "Image", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "image" ] }, "data": { "type": "string", "description": "An image send as part of a prompt to a model. The image is represented as base64.\n\nNote: The models operate on square images. All non-square images are center-cropped\nbefore going to the model, so portions of the image may not be visible.\n\nYou can supply specific cropping parameters if you like, to choose a different area\nof the image than a center-crop. Or, you can always transform the image yourself to\na square before sending it.\n" }, "x": { "type": "integer", "description": "x-coordinate of top left corner of cropping box in pixels" }, "y": { "type": "integer", "description": "y-coordinate of top left corner of cropping box in pixels" }, "size": { "type": "integer", "description": "Size of the cropping square in pixels" }, "controls": { "type": "array", "items": { "type": "object", "required": [ "rect", "factor" ], "properties": { "rect": { "type": "object", "required": [ "left", "top", "width", "height" ], "description": "Bounding box in logical coordinates. From 0 to 1. With (0,0) being the upper left corner,\nand relative to the entire image.\n\nKeep in mind, non-square images are center-cropped by default before going to the model. (You\ncan specify a custom cropping if you want.). Since control coordinates are relative to the\nentire image, all or a portion of your control may be outside the \"model visible area\".\n", "properties": { "left": { "type": "number", "description": "x-coordinate of top left corner of the control bounding box.\nMust be a value between 0 and 1, where 0 is the left corner and 1 is the right corner.\n" }, "top": { "type": "number", "description": "y-coordinate of top left corner of the control bounding box\nMust be a value between 0 and 1, where 0 is the top pixel row and 1 is the bottom row.\n" }, "width": { "type": "number", "description": "width of the control bounding box\nMust be a value between 0 and 1, where 1 means the full width of the image.\n" }, "height": { "type": "number", "description": "height of the control bounding box\nMust be a value between 0 and 1, where 1 means the full height of the image.\n" } } }, "factor": { "type": "number", "description": "Factor to apply to the given token in the attention matrix.\n\n- 0 <= factor < 1 => Suppress the given token\n- factor == 1 => identity operation, no change to attention\n- factor > 1 => Amplify the given token\n" }, "token_overlap": { "type": "string", "enum": [ "partial", "complete" ], "default": "partial", "description": "What to do if a control partially overlaps with an image token.\n\nIf set to \"partial\", the factor will be adjusted proportionally with the amount\nof the token it overlaps. So a factor of 2.0 of a control that only covers half\nof the image \"tile\", would be adjusted to 1.5. (It always moves closer to 1, since\n1 is an identity operation for control factors.)\n\nIf set to \"complete\", the full factor will be applied as long as the control\noverlaps with the token at all.\n" } } } } } }, "TokenIdsPromptItem": { "type": "object", "title": "Token Ids", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "enum": [ "token_ids" ] }, "data": { "type": "array", "items": { "type": "integer" } }, "controls": { "type": "array", "items": { "type": "object", "required": [ "index", "factor" ], "properties": { "index": { "type": "integer", "description": "Index of the token, relative to the list of tokens IDs in the current prompt item.\n" }, "factor": { "type": "number", "description": "Factor to apply to the given token in the attention matrix.\n\n- 0 <= factor < 1 => Suppress the given token\n- factor == 1 => identity operation, no change to attention\n- factor > 1 => Amplify the given token\n" } } } } } }, "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" } ] }, "OptimizedPrompt": { "description": "Describes prompt after optimizations. This field is only returned if the flag `disable_optimizations` flag is not set and the prompt has actually changed.", "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Text", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "data": { "type": "string" } } }, { "type": "object", "title": "Image", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "data": { "type": "string", "description": "base64 encoded image" } } }, { "type": "object", "title": "Token Ids", "properties": { "type": { "type": "string", "enum": [ "token_ids" ] }, "data": { "type": "array", "items": { "type": "integer" } } } } ] } }, "CompletionRequest": { "type": "object", "example": { "model": "llama-3.1-8b-instruct", "prompt": "An apple a day" }, "properties": { "model": { "type": "string", "description": "The name of the model.\nModels and their respective architectures can differ in parameter size and capabilities.\nThe most recent version of the model is always used. The model output contains information as to the model version.\n" }, "hosting": { "$ref": "#/components/schemas/Hosting" }, "prompt": { "$ref": "#/components/schemas/Prompt" }, "maximum_tokens": { "type": "integer", "nullable": "true", "description": "The maximum number of tokens to be generated. Completion will terminate after the maximum number of tokens is\nreached.\n\nIncrease this value to generate longer texts. A text is split into tokens. Usually there are more\ntokens than words. The sum of input tokens and maximum_tokens may not exceed the model's context window size.\n" }, "minimum_tokens": { "type": "integer", "default": "0", "description": "Generate at least this number of tokens before an end-of-text token is generated." }, "echo": { "type": "boolean", "default": "false", "description": "Echo the prompt in the completion. This may be especially helpful when log_probs is set to return logprobs for the prompt.\n" }, "temperature": { "type": "number", "default": "0.0", "nullable": "true", "description": "A higher sampling temperature encourages the model to produce less probable outputs (\"be more creative\"). Values are expected in a range from 0.0 to 1.0. Try high values (e.g., 0.9) for a more \"creative\" response and the default 0.0 for a well defined and repeatable answer. It is advised to use either temperature, top_k, or top_p, but not all three at the same time. If a combination of temperature, top_k or top_p is used, rescaling of logits with temperature will be performed first. Then top_k is applied. Top_p follows last." }, "top_k": { "type": "integer", "default": "0", "nullable": "true", "description": "Introduces random sampling for generated tokens by randomly selecting the next token from the k most likely options. A value larger than 1 encourages the model to be more creative. Set to 0.0 if repeatable output is desired. It is advised to use either temperature, top_k, or top_p, but not all three at the same time. If a combination of temperature, top_k or top_p is used, rescaling of logits with temperature will be performed first. Then top_k is applied. Top_p follows last." }, "top_p": { "type": "number", "default": "0.0", "nullable": "true", "description": "Introduces random sampling for generated tokens by randomly selecting the next token from the smallest possible set of tokens whose cumulative probability exceeds the probability top_p. Set to 0.0 if repeatable output is desired. It is advised to use either temperature, top_k, or top_p, but not all three at the same time. If a combination of temperature, top_k or top_p is used, rescaling of logits with temperature will be performed first. Then top_k is applied. Top_p follows last." }, "presence_penalty": { "type": "number", "default": "0.0", "nullable": "true", "description": "The presence penalty reduces the likelihood of generating tokens that are already present in the\ngenerated text (`repetition_penalties_include_completion=true`) respectively the prompt (`repetition_penalties_include_prompt=true`).\nPresence penalty is independent of the number of occurrences. Increase the value to reduce the likelihood of repeating text.\nAn operation like the following is applied:\n\n logits[t] -> logits[t] - 1 * penalty\n\nwhere `logits[t]` is the logits for any given token. Note that the formula is independent of the number of times\nthat a token appears.\n" }, "frequency_penalty": { "type": "number", "default": "0.0", "nullable": "true", "description": "The frequency penalty reduces the likelihood of generating tokens that are already present in the\ngenerated text (`repetition_penalties_include_completion=true`) respectively the prompt (`repetition_penalties_include_prompt=true`).\nIf `repetition_penalties_include_prompt=True`, this also includes the tokens in the prompt.\nFrequency penalty is dependent on the number of occurrences of a token.\nAn operation like the following is applied:\n\n logits[t] -> logits[t] - count[t] * penalty\n\nwhere `logits[t]` is the logits for any given token and `count[t]` is the number of times that token appears.\n" }, "sequence_penalty": { "type": "number", "default": "0.0", "description": "Increasing the sequence penalty reduces the likelihood of reproducing token sequences that already appear in the prompt\n(if repetition_penalties_include_prompt is True) and prior completion.\n" }, "sequence_penalty_min_length": { "type": "integer", "default": "2", "description": "Minimal number of tokens to be considered as sequence\n" }, "repetition_penalties_include_prompt": { "type": "boolean", "default": "false", "nullable": "true", "description": "Flag deciding whether presence penalty or frequency penalty are updated from tokens in the prompt" }, "repetition_penalties_include_completion": { "type": "boolean", "default": "true", "description": "Flag deciding whether presence penalty or frequency penalty are updated from tokens in the completion" }, "use_multiplicative_presence_penalty": { "type": "boolean", "default": "false", "nullable": "true", "description": "Flag deciding whether presence penalty is applied multiplicatively (True) or additively (False). This changes the formula stated for presence penalty." }, "use_multiplicative_frequency_penalty": { "type": "boolean", "default": "false", "description": "Flag deciding whether frequency penalty is applied multiplicatively (True) or additively (False). This changes the formula stated for frequency penalty." }, "use_multiplicative_sequence_penalty": { "type": "boolean", "default": "false", "description": "Flag deciding whether sequence penalty is applied multiplicatively (True) or additively (False)." }, "penalty_bias": { "type": "string", "nullable": "true", "default": "null", "description": "All tokens in this text will be used in addition to the already penalized tokens for repetition penalties. These consist of the already generated completion tokens and the prompt tokens, if `repetition_penalties_include_prompt` is set to `true`.\n" }, "penalty_exceptions": { "type": "array", "nullable": "true", "items": { "type": "string" }, "description": "List of strings that may be generated without penalty, regardless of other penalty settings.\nBy default, we will also include any `stop_sequences` you have set, since completion performance can be degraded if expected stop sequences are penalized.\nYou can disable this behavior by setting `penalty_exceptions_include_stop_sequences` to `false`.\n" }, "penalty_exceptions_include_stop_sequences": { "type": "boolean", "default": "true", "nullable": "true", "description": "By default we include all `stop_sequences` in `penalty_exceptions`, so as not to penalise the presence of stop sequences that are present in few-shot prompts to give structure to your completions.\n\nYou can set this to `false` if you do not want this behaviour.\n\nSee the description of `penalty_exceptions` for more information on what `penalty_exceptions` are used for.\n" }, "best_of": { "type": "integer", "nullable": "true", "default": "1", "maximum": "100", "description": "If a value is given, the number of `best_of` completions will be generated on the server side. The completion with the highest log probability per token is returned. If the parameter `n` is greater than 1 more than 1 (`n`) completions will be returned. `best_of` must be strictly greater than `n`." }, "n": { "type": "integer", "default": "1", "nullable": "true", "description": "The number of completions to return. If argmax sampling is used (temperature, top_k, top_p are all default) the same completions will be produced. This parameter should only be increased if random sampling is used." }, "logit_bias": { "type": "object", "nullable": "true" }, "log_probs": { "type": "integer", "default": "null", "nullable": "true", "minimum": "0", "maximum": "20", "description": "Number of top log probabilities for each token generated. Log probabilities can be used in downstream tasks or to assess the model's certainty when producing tokens. No log probabilities are returned if set to None. Log probabilities of generated tokens are returned if set to 0. Log probabilities of generated tokens and top n log probabilities are returned if set to n." }, "stop_sequences": { "type": "array", "nullable": "true", "description": "List of strings that will stop generation if they're generated. Stop sequences may be helpful in structured texts. Say the user has specified \"tor away\" as one of the requested stop sequences and the model has generated the following sequence of tokens [\"An\", \" apple\", \" a\", \" day\", \" keeps\", \" the\", \" doctor\", \" away\"]. The user will see \"An apple a day keeps the\" as the model's response, omitting the last two tokens which contain the stop sequence. Note that even though \" doc\" is not part of the stop sequence \"tor away\", it won't appear in the user output since it is part of the token \" doctor\" which contains part of the stop sequence.\n", "items": { "type": "string" } }, "tokens": { "type": "boolean", "default": "false", "nullable": "true", "description": "Flag indicating whether individual tokens of the completion should be returned (True) or whether solely the generated text (i.e. the completion) is sufficient (False)." }, "raw_completion": { "type": "boolean", "default": "false", "description": "Setting this parameter to true forces the raw completion of the model to be returned.\nFor some models, we may optimize the completion that was generated by the model and\nreturn the optimized completion in the completion field of the `CompletionResponse`.\nThe raw completion, if returned, will contain the un-optimized completion.\nSetting tokens to true or log_probs to any value will also trigger the raw completion\nto be returned.\n" }, "disable_optimizations": { "type": "boolean", "default": "false", "nullable": "true", "description": "We continually research optimal ways to work with our models. By default, we apply these optimizations to both your prompt and completion for you.\nOur goal is to improve your results while using our API. But you can always pass `disable_optimizations: true` and we will leave your prompt and completion untouched.\n" }, "completion_bias_inclusion": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Bias the completion to only generate options within this list;\nall other tokens are disregarded at sampling\n\nNote that strings in the inclusion list must not be prefixes\nof strings in the exclusion list and vice versa\n" }, "completion_bias_inclusion_first_token_only": { "type": "boolean", "default": "false", "description": "Only consider the first token for the completion_bias_inclusion\n" }, "completion_bias_exclusion": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Bias the completion to NOT generate options within this list;\nall other tokens are unaffected in sampling\n\nNote that strings in the inclusion list must not be prefixes\nof strings in the exclusion list and vice versa\n" }, "completion_bias_exclusion_first_token_only": { "type": "boolean", "default": "false", "description": "Only consider the first token for the completion_bias_exclusion\n" }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" }, "stream": { "type": "boolean", "default": "false", "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.\n" }, "steering_concepts": { "type": "array", "items": { "$ref": "#/components/schemas/SteeringConceptRef" }, "default": [], "description": "Specifies how the output of the model should be steered. This steers\nthe output in the direction given by positive examples associated to\nthe steering concept and away from the negative examples.\n\nCurrently only one steering concept at a time is supported.\n" } }, "required": [ "model", "prompt" ] }, "CompletionResponse": { "description": "Response object being returned when streaming is disabled.", "type": "object", "example": { "completions": [ { "completion": "keeps the doctor away.", "finish_reason": "maximum_tokens" } ], "model_version": "2021-12", "optimized_prompt": "An apple a day", "num_tokens_prompt_total": "4", "num_tokens_generated": "5" }, "properties": { "model_version": { "type": "string", "description": "model name and version (if any) of the used model for inference" }, "completions": { "type": "array", "description": "list of completions; may contain only one entry if no more are requested (see parameter n)", "items": { "type": "object", "properties": { "log_probs": { "type": "object", "nullable": "true", "description": "list with a dictionary for each generated token. The dictionary maps the keys' tokens to the respective log probabilities. This field is only returned if requested with the parameter \"log_probs\"." }, "completion": { "type": "string", "nullable": "false", "description": "generated completion on the basis of the prompt" }, "raw_completion": { "type": "string", "nullable": "true", "description": "For some models, we may optimize the completion that was generated by the model and\nreturn the optimized completion in the completion field of the CompletionResponse.\nThe raw completion, if returned, will contain the un-optimized completion.\nSetting the parameter `raw_completion` in the CompletionRequest to true forces the\nraw completion of the model to be returned.\nSetting tokens to true or log_probs to any value will also trigger the raw\ncompletion to be returned.\n" }, "completion_tokens": { "type": "array", "items": { "type": "string" }, "description": "completion split into tokens. This field is only returned if requested with the parameter \"tokens\"." }, "finish_reason": { "type": "string", "nullable": "true", "description": "reason for termination of generation. This may be a stop sequence or maximum number of tokens reached." } } } }, "optimized_prompt": { "$ref": "#/components/schemas/OptimizedPrompt" }, "num_tokens_prompt_total": { "type": "integer", "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" }, "num_tokens_generated": { "type": "integer", "description": "Number of tokens combined across all completion tasks.\nIf multiple completions are returned or best_of is set to a value greater than 1 then\nthis value contains the combined generated token count.\n" } } }, "StreamChunk": { "description": "Response object being returned continuously per completion stream during transmission.", "type": "object", "example": { "type": "stream_chunk", "index": "0", "completion": "keeps the doctor away." }, "required": [ "type", "index", "completion" ], "properties": { "type": { "description": "Marker tag denoting the type of the stream item. Will always be `stream_chunk` for `StreamChunk`s.", "type": "string", "enum": [ "stream_chunk" ] }, "index": { "description": "The index of the current completion. Use this parameter to associate chunks with the correct message stream as chunks might arrive out of order. This is mostly relevant when multiple completions are requested.", "type": "integer" }, "log_probs": { "description": "list with a dictionary for each generated token. The dictionary maps the keys' tokens to the respective log probabilities. This field is only returned if requested with the parameter \"log_probs\".", "type": "object" }, "completion": { "description": "generated completion on the basis of the prompt", "type": "string" }, "raw_completion": { "description": "For some models, we may optimize the completion that was generated by the model and\nreturn the optimized completion in the completion field of the CompletionResponse.\nThe raw completion, if returned, will contain the un-optimized completion.\nSetting the parameter `raw_completion` in the CompletionRequest to true forces the\nraw completion of the model to be returned.\nSetting tokens to true or log_probs to any value will also trigger the raw\ncompletion to be returned.\n", "type": "string" }, "completion_tokens": { "description": "completion split into tokens. This field is only returned if requested with the parameter \"tokens\".", "type": "array", "items": { "type": "string" } } } }, "StreamSummary": { "description": "Response object being returned once per completion stream at the end of a stream.", "type": "object", "example": { "type": "stream_summary", "index": "0", "model_version": "2021-12", "finish_reason": "maximum_tokens" }, "required": [ "type", "index", "model_version", "finish_reason" ], "properties": { "type": { "description": "Marker tag denoting the type of the stream item. Will always be `stream_summary` for `StreamSummary`s.", "type": "string", "enum": [ "stream_summary" ] }, "index": { "description": "The index of the current completion. Use this parameter to associate chunks with the correct message stream as chunks might arrive out of order. This is mostly relevant when multiple completions are requested.", "type": "integer" }, "model_version": { "type": "string", "description": "model name and version (if any) of the used model for inference" }, "finish_reason": { "type": "string", "description": "reason for termination of generation. This may be a stop sequence or maximum number of tokens reached." } } }, "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.\nIf multiple completions are returned or best_of is set to a value greater than 1 then\nthis value contains the combined generated token count. ChatRequest:\n", "type": "integer" } } }, "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.\n\nThe requested model must be eligible for chat completions.\n", "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.\n\nThe penalty is cumulative. The more a token is mentioned in the completion, the more its probability will decrease.\n", "type": "number", "minimum": "-2", "maximum": "2" }, "logit_bias": { "description": "When specified, the provided hash map will affect the likelihood of the specified token IDs (!) appearing in the completion.\n\nMathematically, 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.\n\nNote that since JSON does not support integer keys, the token IDs are represented as strings.\n", "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.\n\nThe 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.\n", "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.\n\nWhen no value is provided, one completion will be returned.\n", "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\n\nThe penalty is not cumulative. Mentioning a token more than once will not increase the penalty further.\n", "type": "number", "minimum": "-2", "maximum": "2" }, "response_format": { "description": "An object specifying the format that the model must output.\nThe response format can be passed either directly in the http request,\nor via the Aleph Alpha Client using a pydantic or a JSONSchema object.\nAlso compatible with the OpenAI client passing a pydantic object\nas response_format.\n", "$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.\n", "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.\n\nMathematically, the temperature is used to divide the logits before sampling. A temperature of 0 will always return the most likely token.\n\nWhen no value is provided, the default value of 1 will be used.\n", "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.\n\nWhen no value is provided, the default value of 1 will be used.\n", "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\nthe output in the direction given by positive examples associated to\nthe steering concept and away from the negative examples.\n\nCurrently only one steering concept at a time is supported.\n" }, "tools": { "type": "array", "description": "A list of tools the model may call. Currently, only functions are supported as a tool. Use\nthis to provide a list of functions the model may generate JSON inputs for. A max of 128\nfunctions are supported.\n", "items": { "$ref": "#/components/schemas/ChatRequestTool" } }, "tool_choice": { "description": "Controls which (if any) tool is called by the model.\n`none` means the model will not call any tool and instead generates a message.\n`auto` means the model can pick between generating a message or calling one or more tools.\n`required` means the model must call one or more tools.\nSpecifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces\nthe model to call that tool.\n`none` is the default when no tools are present. `auto` is the default if tools are present.\n", "anyOf": [ { "type": "string", "description": "`none` means the model will not call any tool and instead generates a message. `auto` means the\nmodel can pick between generating a message or calling one or more tools. `required` means the\nmodel must call one or more tools.\n", "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": { "type": "string", "description": "The name of the function to call." } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } ] }, "parallel_tool_calls": { "deprecated": "true", "description": "This parameter is unsupported and will be rejected." }, "user": { "deprecated": "true", "description": "This parameter is unsupported and will be ignored." } } }, "ChatRequestMessage": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "description": "The role of the current message.\n\nOnly one optional \"system\" message is allowed at the beginning of the conversation. The remaining conversation:\n- Must alternate between \"user\" and \"assistant\" messages.\n- Must begin with a \"user\" message.\n- Must end with a \"user\" message.\n", "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "description": "The content of the current message respecting the requirements of the chat template. The exact format strongly depends on the configured chat template. System prompt and following messages could have different formats.", "oneOf": [ { "type": "string", "description": "Text only message" }, { "type": "array", "description": "Message with arbitrary number of images and text in any order", "items": { "oneOf": [ { "type": "object", "required": [ "type", "image_url" ], "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "base64 encoded image data url" }, "detail": { "type": "string", "enum": [ "auto" ], "description": "Unsupported parameter, only allowed to be set to \"auto\"" } } } } }, { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Text content of the message" } } } ] } } ] }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.", "items": { "$ref": "#/components/schemas/ChatRequestMessageToolCall" } }, "tool_call_id": { "type": "string", "description": "Tool call that this message is responding to." }, "name": { "deprecated": "true", "description": "This parameter is unsupported and will be ignored." } } }, "ChatRequestTool": { "type": "object", "title": "Function tool", "description": "A function tool that can be used to generate a response.\n", "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" ] }, "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\nfunction.\n" }, "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,\nwith a maximum length of 64.\n" }, "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\nmodel will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema\nis supported when `strict` is `true`. Learn more about Structured Outputs in [our\ndocs](https://docs.aleph-alpha.com/products/pharia-ai/pharia-os/references/inference/structured-output/).\n" } }, "required": [ "name" ] }, "FunctionParameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object. Omitting `parameters`\ndefines a function with an empty parameter list.\n", "additionalProperties": "true" }, "ChatRequestMessageToolCall": { "type": "object", "title": "Function tool call", "description": "A call to a function tool created by the model.\n", "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 function to call." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format." } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] }, "ChatResponse": { "type": "object", "example": { "id": "d902da3c-67dd-47d6-acfc-b7dbcb01eb9d", "choices": [ { "finish_reason": "stop", "index": "0", "message": { "role": "assistant", "content": "I'd be happy to help you with your homework. What subject and what specific problem or assignment are you working on? Share as much information as you can, and I'll do my best to assist you." }, "logprobs": "null" } ], "created": "1739975747", "model": "llama-3.1-8b-instruct", "system_fingerprint": ".unknown.", "object": "chat.completion", "usage": { "prompt_tokens": "31", "completion_tokens": "43", "total_tokens": "74" } }, "properties": { "id": { "description": "An ID that is unique throughout the given request. When multiple chunks are returned using server-sent events, this ID will be the same for all of them.", "type": "string" }, "choices": { "description": "A list of chat completion choices. Can be more than one if `n` is greater than 1.", "type": "array", "items": { "$ref": "#/components/schemas/ChatResponseMessage" } }, "created": { "description": "The Unix timestamp (in seconds) of when the chat completion was created.", "type": "integer" }, "model": { "description": "The ID of the model that generated the completion.", "type": "string" }, "system_fingerprint": { "description": "The specific version of the model that generated the completion. This field can be used to track inconsistencies between calls to different deployments of otherwise identical models.\n\nWhen streaming is enabled, the value is only set in the last chunk of a completion and `null` otherwise.\n", "type": "string" }, "object": { "description": "Will be `chat.completion` by default and `chat.completion.chunk` when streaming is enabled.", "type": "string", "enum": [ "chat.completion", "chat.completion.chunk" ] }, "usage": { "description": "Usage statistics for the completion request.\n\nWhen streaming is enabled, this field will be `null` by default. To include an additional usage-only message in the response stream, set `stream_options.include_usage` to `true`.\n", "type": "object", "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "properties": { "completion_tokens": { "description": "Number of tokens in the generated completion.", "type": "integer" }, "prompt_tokens": { "description": "Number of tokens in the prompt.", "type": "integer" }, "total_tokens": { "description": "Total number of tokens used in the request (prompt + completion).", "type": "integer" } } } } }, "ChatResponseMessage": { "type": "object", "required": [ "index" ], "properties": { "finish_reason": { "description": "The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence or `length` if the maximum number of tokens specified in the request was reached. If the API is unable to understand the stop reason emitted by one of the workers, `content_filter` is returned.\n\nWhen streaming is enabled, the value is only set in the last chunk of a completion and `null` otherwise.\n", "type": "string", "enum": [ "stop", "length", "content_filter" ] }, "index": { "description": "The index of the current chat completion in the conversation. Use this parameter to associate chunks with the correct message stream as chunks might arrive out of order. This is mostly relevant when streaming is enabled and multiple completions are requested.", "type": "integer" }, "message": { "description": "Chat completion generated by the model when streaming is disabled.", "type": "object", "required": [ "role", "content" ], "properties": { "role": { "description": "The role of the current chat completion. Will `assistant`.", "type": "string", "enum": [ "assistant" ] }, "content": { "description": "The content of the current chat completion.", "type": "string" } } }, "delta": { "description": "Chat completion chunk generated by the model when streaming is enabled.", "type": "object", "required": [ "content" ], "properties": { "role": { "description": "The role of the current chat completion. Will be `assistant` for the first chunk of every completion stream and missing for the remaining chunks.", "type": "string", "enum": [ "assistant" ] }, "content": { "description": "The content of the current chat completion. Will be empty for the first chunk of every completion stream and non-empty for the remaining chunks.", "type": "string" } } }, "logprobs": { "description": "Log probability information for the choice. `null` if this is the end of a completion stream.", "type": "object", "properties": { "content": { "description": "A list of message content tokens with log probability information.", "type": "array", "items": { "$ref": "#/components/schemas/ChatResponseLogprobs" } } } } } }, "ChatResponseLogprobs": { "type": "object", "required": [ "token", "logprob", "bytes", "top_logprobs" ], "properties": { "token": { "description": "The token.", "type": "string" }, "logprob": { "description": "The log probability of the token. If the log probability is not returned by the worker, -9999.0 is used as a fallback.", "type": "number" }, "bytes": { "description": "A list of integers representing the UTF-8 bytes representation of the token.", "type": "array", "items": { "type": "integer" } }, "top_logprobs": { "description": "List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.", "type": "array", "items": { "$ref": "#/components/schemas/ChatResponseTopLogprob" } } } }, "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" } } } }, "ExplanationRequest": { "type": "object", "properties": { "model": { "type": "string", "description": "Name of the model to use." }, "hosting": { "type": "string", "nullable": "true", "enum": [ "aleph-alpha" ], "description": "Determines in which datacenters the request may be processed.\nYou can either set the parameter to \"aleph-alpha\" or omit it (defaulting to None).\n\nNot setting this value, or setting it to None, gives us maximal flexibility in processing your request in our\nown datacenters and on servers hosted with other providers. Choose this option for maximal availability.\n\nSetting it to \"aleph-alpha\" allows us to only process the request in our own datacenters.\nChoose this option for maximal data privacy.\n" }, "prompt": { "$ref": "#/components/schemas/Prompt" }, "target": { "type": "string", "description": "The completion string to be explained based on model probabilities.", "nullable": "true" }, "control_factor": { "type": "number", "default": "0.1", "description": "Factor to apply to the given token in the attention matrix.\n\n- 0 <= factor < 1 => Suppress the given token\n- factor == 1 => identity operation, no change to attention\n- factor > 1 => Amplify the given token\n" }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" }, "postprocessing": { "type": "string", "enum": [ "none", "absolute", "square" ], "default": "none", "description": "Optionally apply postprocessing to the difference in cross entropy scores for each token.\n\"none\": Apply no postprocessing.\n\"absolute\": Return the absolute value of each value.\n\"square\": Square each value\n" }, "normalize": { "type": "boolean", "default": "false", "description": "Return normalized scores. Minimum score becomes 0 and maximum score becomes 1. Applied after any postprocessing\n" }, "prompt_granularity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "token", "word", "sentence", "paragraph", "custom" ], "description": "At which granularity should the target be explained in terms of the prompt.\nIf you choose, for example, \"sentence\" then we report the importance score of each\nsentence in the prompt towards generating the target output.\n\nIf you do not choose a granularity then we will try to find the granularity that\nbrings you closest to around 30 explanations. For large documents, this would likely\nbe sentences. For short prompts this might be individual words or even tokens.\n\nIf you choose a custom granularity then you must provide a custom delimiter. We then\nsplit your prompt by that delimiter. This might be helpful if you are using few-shot\nprompts that contain stop sequences.\n\nFor image prompt items, the granularities determine into how many tiles we divide\nthe image for the explanation.\n\"token\" -> 12x12\n\"word\" -> 6x6\n\"sentence\" -> 3x3\n\"paragraph\" -> 1\n" }, "delimiter": { "type": "string", "description": "A delimiter string to split the prompt on if \"custom\" granularity is chosen.\n" } } }, "target_granularity": { "type": "string", "enum": [ "complete", "token" ], "default": "complete", "description": "How many explanations should be returned in the output.\n\n\"complete\" -> Return one explanation for the entire target. Helpful in many cases to determine which parts of the prompt contribute overall to the given completion.\n\"token\" -> Return one explanation for each token in the target.\n" }, "control_token_overlap": { "type": "string", "enum": [ "partial", "complete" ], "default": "partial", "description": "What to do if a control partially overlaps with a text or image token.\n\nIf set to \"partial\", the factor will be adjusted proportionally with the amount\nof the token it overlaps. So a factor of 2.0 of a control that only covers 2 of\n4 token characters, would be adjusted to 1.5. (It always moves closer to 1, since\n1 is an identity operation for control factors.)\n\nIf set to \"complete\", the full factor will be applied as long as the control\noverlaps with the token at all.\n" } }, "required": [ "model", "prompt", "target" ] }, "TokenIdsPromptItemImportance": { "type": "object", "description": "Explains the importance of a request prompt item of type \"token_ids\".\nWill contain one floating point importance value for each token in the same order as in\nthe original prompt.\n", "properties": { "type": { "type": "string", "enum": [ "token_ids" ] }, "scores": { "type": "array", "items": { "type": "number" } } } }, "TargetItemImportance": { "type": "object", "description": "Explains the importance of text in the target string that came before the currently\nto-be-explained target token. The amount of items in the \"scores\" array depends on the\ngranularity setting.\nEach score object contains an inclusive start character and a length of the substring plus\na floating point score value.\n", "properties": { "type": { "type": "string", "enum": [ "target" ] }, "scores": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer" }, "length": { "type": "integer" }, "score": { "type": "number" } } } } } }, "TextPromptItemImportance": { "type": "object", "description": "Explains the importance of a text prompt item.\nThe amount of items in the \"scores\" array depends on the granularity setting.\nEach score object contains an inclusive start character and a length of the substring plus\na floating point score value.\n", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "scores": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer" }, "length": { "type": "integer" }, "score": { "type": "number" } } } } } }, "ImagePromptItemImportance": { "type": "object", "description": "Explains the importance of an image prompt item.\nThe amount of items in the \"scores\" array depends on the granularity setting.\nEach score object contains the top-left corner of a rectangular area in the image prompt.\nThe coordinates are all between 0 and 1 in terms of the total image size\n", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "scores": { "type": "array", "items": { "type": "object", "properties": { "rect": { "type": "object", "properties": { "top": { "type": "number" }, "left": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } } }, "score": { "type": "number" } } } } } }, "ExplanationResponse": { "description": "The top-level response data structure that will be returned from an explanation request.\n", "type": "object", "properties": { "model_version": { "type": "string" }, "explanations": { "description": "This array will contain one explanation object for each token in the target string.\n", "type": "array", "items": { "type": "object", "properties": { "target": { "description": "The string representation of the target token which is being explained\n", "type": "string" }, "items": { "description": "Contains one item for each prompt item (in order), and the last item refers to the\ntarget.\n", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TokenIdsPromptItemImportance" }, { "$ref": "#/components/schemas/TargetItemImportance" }, { "$ref": "#/components/schemas/TextPromptItemImportance" }, { "$ref": "#/components/schemas/ImagePromptItemImportance" } ] } } } } } } }, "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.\n" }, "normalize": { "type": "boolean", "default": "false", "description": "Return normalized embeddings. This can be used to save on additional compute when applying a cosine similarity metric.\n" }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" } }, "required": [ "model", "prompt" ] }, "EmbeddingResponse": { "type": "object", "example": { "model_version": "2021-12", "embeddings": { "layer_0": { "max": [ "-0.053497314", "0.0053749084", "0.06427002", "0.05316162", "-0.0044059753", "..." ] }, "layer_1": { "max": [ "0.14086914", "-0.24780273", "1.3232422", "-0.07055664", "1.2148438", "..." ] } }, "tokens": "null", "num_tokens_prompt_total": "42" }, "properties": { "model_version": { "type": "string", "description": "model name and version (if any) of the used model for inference" }, "embeddings": { "type": "object", "nullable": "true", "description": "embeddings:\n - pooling: a dict with layer names as keys and and pooling output as values. A pooling output is a dict with pooling operation as key and a pooled embedding (list of floats) as values\n" }, "tokens": { "type": "array", "items": { "type": "string" }, "nullable": "true" }, "num_tokens_prompt_total": { "type": "integer", "description": "Number of tokens in the prompt.\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" } } }, "SemanticEmbeddingCompressToSize": { "type": "integer", "enum": [ "128" ], "description": "The default behavior is to return the full embedding with 5120 dimensions. With this parameter you can compress the returned embedding to 128 dimensions.\nThe compression is expected to result in a small drop in accuracy performance (4-6%), with the benefit of being much smaller, which makes comparing these embeddings much faster for use cases where speed is critical.\nWith the compressed embedding can also perform better if you are embedding really short texts or documents.\n" }, "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.\n\n`\"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.\n\n`\"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.\n\n`\"query\"`-embeddings are optimized for shorter texts, such as questions or keywords.\n\n`\"document\"`-embeddings are optimized for larger pieces of text to compare queries against.\n" }, "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.\n" }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" } }, "required": [ "prompt", "representation" ] }, "InstructableEmbeddingRequest": { "type": "object", "example": { "model": "pharia-1-embedding-4608-control", "input": "An apple a day keeps the doctor away.", "instruction": "Represent the user's question about rivers to find a relevant wikipedia paragraph" }, "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 with instructions, please refer to the `/model-settings` endpoint." }, "hosting": { "$ref": "#/components/schemas/Hosting" }, "input": { "$ref": "#/components/schemas/Prompt" }, "instruction": { "type": "string", "description": "To further improve performance by steering the model, you can use\ninstructions. Instructions can help the model understand nuances of\nyour specific data and ultimately lead to embeddings that are more\nuseful for your use-case. In this case, we aim to further increase\nthe absolute difference between the cosine similarities.\nInstruction can also be the empty string.\n" }, "normalize": { "type": "boolean", "default": "false", "description": "Return normalized embeddings. This can be used to save on additional compute when applying a cosine similarity metric.\n" }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" } }, "required": [ "input", "instruction" ] }, "SemanticEmbeddingResponse": { "type": "object", "example": { "model_version": "2021-12", "embedding": [ "-0.053497314", "0.0053749084", "0.06427002", "0.05316162", "-0.0044059753", "..." ], "num_tokens_prompt_total": "42" }, "properties": { "model_version": { "type": "string", "description": "model name and version (if any) of the used model for inference" }, "embedding": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "A list of floats that can be used to compare against other embeddings." }, "num_tokens_prompt_total": { "type": "integer", "description": "Number of tokens in the prompt.\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" } } }, "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.\n\n`\"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.\n\n`\"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.\n\n`\"query\"`-embeddings are optimized for shorter texts, such as questions or keywords.\n\n`\"document\"`-embeddings are optimized for larger pieces of text to compare queries against.\n" }, "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.\n" }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" } }, "required": [ "prompts", "representation" ] }, "BatchSemanticEmbeddingResponse": { "type": "object", "example": { "model_version": "2021-12", "embeddings": [ [ "-0.053497314", "0.0053749084", "0.06427002", "0.05316162", "-0.0044059753", "..." ], [ "-0.053497314", "0.0053749084", "0.06427002", "0.05316162", "-0.0044059753", "..." ] ], "num_tokens_prompt_total": "42" }, "properties": { "model_version": { "type": "string", "description": "model name and version (if any) of the used model for inference" }, "embeddings": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "float" }, "description": "A list of floats that can be used to compare against other embeddings." } }, "num_tokens_prompt_total": { "type": "integer", "description": "Number of tokens in the all prompts combined.\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" } } }, "EvaluationRequest": { "type": "object", "example": { "model": "llama-3.1-8b-instruct", "prompt": "An apple a day", "completion_expected": "keeps the doctor away." }, "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" }, "completion_expected": { "type": "string", "description": "The completion that you would expect to be completed. Unconditional completion can be used with an empty string (default). The prompt may contain a zero shot or few shot task." }, "contextual_control_threshold": { "type": "number", "default": "null", "nullable": "true", "description": "If set to `null`, attention control parameters only apply to those tokens that have\nexplicitly been set in the request.\nIf set to a non-null value, we apply the control parameters to similar tokens as well.\nControls that have been applied to one token will then be applied to all other tokens\nthat have at least the similarity score defined by this parameter.\nThe similarity score is the cosine similarity of token embeddings.\n" }, "control_log_additive": { "type": "boolean", "default": "true", "description": "`true`: apply controls on prompt items by adding the `log(control_factor)` to attention scores.\n`false`: apply controls on prompt items by `(attention_scores - -attention_scores.min(-1)) * control_factor`\n" } }, "required": [ "model", "prompt", "completion_expected" ] }, "EvaluationResponse": { "type": "object", "example": { "model_version": "2021-12", "result": { "log_probability": "-1.2281955", "log_perplexity": "1.2281955", "log_perplexity_per_token": "0.24563909", "log_perplexity_per_character": "1.2281955", "correct_greedy": "true", "token_count": "5", "character_count": "1", "completion": " keeps the doctor away." }, "num_tokens_prompt_total": "9" }, "properties": { "model_version": { "type": "string", "description": "model name and version (if any) of the used model for inference" }, "result": { "type": "object", "description": "dictionary with result metrics of the evaluation", "properties": { "log_probability": { "type": "number", "nullable": "true", "description": "log probability of producing the expected completion given the prompt. This metric refers to all tokens and is therefore dependent on the used tokenizer. It cannot be directly compared among models with different tokenizers." }, "log_perplexity": { "type": "number", "nullable": "true", "description": "log perplexity associated with the expected completion given the prompt. This metric refers to all tokens and is therefore dependent on the used tokenizer. It cannot be directly compared among models with different tokenizers." }, "log_perplexity_per_token": { "type": "number", "nullable": "true", "description": "log perplexity associated with the expected completion given the prompt normalized for the number of tokens. This metric computes an average per token and is therefore dependent on the used tokenizer. It cannot be directly compared among models with different tokenizers." }, "log_perplexity_per_character": { "type": "number", "nullable": "true", "description": "log perplexity associated with the expected completion given the prompt normalized for the number of characters. This metric is independent of any tokenizer. It can be directly compared among models with different tokenizers." }, "correct_greedy": { "type": "boolean", "nullable": "true", "description": "Flag indicating whether a greedy completion would have produced the expected completion." }, "token_count": { "type": "integer", "nullable": "true", "description": "Number of tokens in the expected completion." }, "character_count": { "type": "integer", "nullable": "true", "description": "Number of characters in the expected completion." }, "completion": { "type": "string", "nullable": "true", "description": "argmax completion given the input consisting of prompt and expected completion. This may be used as an indicator of what the model would have produced. As only one single forward is performed an incoherent text could be produced especially for long expected completions." } } }, "num_tokens_prompt_total": { "type": "integer", "description": "The sum over the number of tokens of both the `prompt` and the `completion_expected` fields.\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" } } }, "TokenizationRequest": { "type": "object", "example": { "model": "llama-3.1-8b-instruct", "prompt": "An apple a day keeps the doctor away.", "tokens": "true", "token_ids": "true" }, "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "tokens": { "type": "boolean" }, "token_ids": { "type": "boolean" } }, "required": [ "model", "prompt", "tokens", "token_ids" ] }, "TokenizationResponse": { "type": "object", "example": { "tokens": [ "\u0120An", "\u0120apple", "\u0120a", "\u0120day", "\u0120keeps", "\u0120the", "\u0120doctor", "\u0120away", "." ], "token_ids": [ "560", "34438", "246", "1966", "18075", "275", "8809", "3476", "17" ] }, "properties": { "tokens": { "type": "array", "items": { "type": "string" } }, "token_ids": { "type": "array", "items": { "type": "integer" } } } }, "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" ] }, "DetokenizationResponse": { "type": "object", "example": { "result": " An apple a day keeps the doctor away." }, "properties": { "result": { "type": "string" } } }, "CreateSteeringConceptRequest": { "type": "object", "example": { "examples": [ { "negative": "I appreciate your valuable feedback on this matter.", "positive": "Thanks for the real talk, fam." }, { "negative": "Please ensure all documentation is submitted by the deadline.", "positive": "Get those papers in ASAP or it's gonna be big yikes." } ] }, "properties": { "examples": { "type": "array", "items": { "type": "object", "properties": { "negative": { "type": "string" }, "positive": { "type": "string" } } } } }, "required": [ "examples" ] }, "CreateSteeringConceptResponse": { "type": "object", "example": { "id": "c925b346425c37c380920df3c5f542000d4b54ed3f183313e274328c921879e0" }, "properties": { "id": { "type": "string" } } }, "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" } } } }, "UserDetail": { "type": "object", "required": [ "id", "email", "role", "credits_remaining", "invoice_allowed", "out_of_credits_threshold", "terms_of_service_version" ], "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "description": "Email address of the user" }, "role": { "type": "string", "description": "Role of the user" }, "credits_remaining": { "type": "number", "description": "Unused and always 0. Maintained for backwards compatibility. In the past a positive number indicated the credits a pre-paid user had still available and a negative number the amount of credits the user would be billed for." }, "invoice_allowed": { "type": "boolean", "description": "Unused and always true. Maintained for backwards compatibility. In the past this attribute indicated whether the user would be billed for using the API or be using pre-paid credits." }, "out_of_credits_threshold": { "type": "integer", "description": "Unused and always 0 for reasons of backwards compatibility. In the past this attribute controlled then a user was notified about buying more credits for the SaaS offering." }, "terms_of_service_version": { "type": "string", "description": "Version string of the terms of service that the user has accepted" } } }, "Permissions": { "title": "List of permissions", "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" } } } }, "SteeringConceptRef": { "oneOf": [ { "$ref": "#/components/schemas/WorkerSteeringConcept" }, { "$ref": "#/components/schemas/SteeringConceptId" } ] }, "WorkerSteeringConcept": { "type": "string", "pattern": "^_worker/[a-zA-Z0-9-_]{1,64}$", "description": "A reference to a worker-defined steering concept. The value must be a\nstring starting with `_worker/` followed by a name matching the pattern\n`^[a-zA-Z0-9-_]{1,64}$`.\n" }, "SteeringConceptId": { "type": "string", "pattern": "^[a-aA-Z0-9-_]+$", "description": "The ID of a steering concept that was created using the `steering_concepts` endpoint.\n" }, "EmbeddingV2Request": { "type": "object", "example": { "model": "qwen3-embedding-0.6b", "input": "this text will be embedded", "encoding_format": "float", "dimensions": "128" }, "properties": { "model": { "type": "string", "description": "The name of the model used to generate the embedding." }, "input": { "description": "Input text to be embedded.", "oneOf": [ { "type": "string", "title": "String", "description": "The string that will be turned into an embedding." }, { "type": "array", "title": "Array of strings", "items": { "type": "string" }, "description": "The array of strings that will be turned into an embedding. We will return an embedding for each element in the array" }, { "type": "array", "title": "Array of integers", "items": { "type": "integer" }, "description": "The array of integers that will be turned into an embedding. Each integer represents a token. An array of tokens represents a string for which the embedding is generated." }, { "type": "array", "title": "Array of arrays of integers", "items": { "type": "array", "items": { "type": "integer" } }, "description": "The array of arrays containing integers that will be turned into an embedding. An array of tokens represents a string for which the embedding is generated. We will return an embedding for each element in the outer array." } ] }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "description": "The format to return the embeddings in. Can be either `float` or `base64`." }, "dimensions": { "type": "integer", "minimum": "1", "description": "The number of dimensions the resulting output embeddings should have. Not supported by all models." }, "user": { "type": "string", "description": "This parameter is unsupported and will be rejected.", "deprecated": "true" } }, "required": [ "model", "input" ] }, "EmbeddingV2Response": { "type": "object", "example": { "object": "list", "data": [ { "object": "embedding", "embedding": [ "0.0023064255", "-0.009327292", "..." ], "index": "0" } ], "model": "qwen3-embedding-0.6b", "usage": { "prompt_tokens": "8", "total_tokens": "8" } }, "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "The object type, which is always \"list\"." }, "data": { "type": "array", "description": "The list of embeddings generated by the model.", "items": { "$ref": "#/components/schemas/EmbeddingV2ResponseData" } }, "model": { "type": "string", "description": "The name of the model used to generate the embedding." }, "usage": { "$ref": "#/components/schemas/EmbeddingV2Usage" } } }, "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" ] }, "EmbeddingV2Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer", "description": "The number of tokens in the input." }, "total_tokens": { "type": "integer", "description": "The total number of tokens used by the request." } }, "required": [ "prompt_tokens", "total_tokens" ] }, "TranscribeSegment": { "type": "object", "properties": { "start": { "type": "number", "format": "float", "description": "Start time of the segment in seconds" }, "end": { "type": "number", "format": "float", "description": "End time of the segment in seconds" }, "text": { "type": "string", "description": "The transcribed text for this segment" }, "tokens": { "type": "array", "items": { "type": "integer" }, "description": "Token IDs for the transcribed text" } } }, "TranscribeRequest": { "type": "object", "properties": { "audiofile": { "type": "string", "format": "binary", "description": "The audio file to transcribe. For supported formats, see the documentation of the model that you are using.\n" }, "metadata": { "type": "object", "description": "Example: {\"model\":\"transcription-model\", \"language\":\"de\"}\n", "properties": { "model": { "type": "string", "description": "The name of the transcription model to use" }, "language": { "type": "string", "description": "Optional language code for the transcription. Must be specified using ISO 639-1 language codes such as\n\"en\" for English, \"de\" for German, \"fr\" for French, etc.\nFor information on supported languages, refer to the documentation of the model that you are using.\n" } }, "required": [ "model" ] } } }, "TranscribeResponse": { "type": "object", "example": { "transcription": "This is an example transcription. It contains two segments.", "segments": [ { "start": "0.0", "end": "2.5", "text": "This is an example transcription.", "tokens": [ "1234", "5678", "9012", "3456", "7890" ] }, { "start": "2.5", "end": "4.0", "text": "It contains two segments.", "tokens": [ "3456", "7890", "1234", "5678" ] } ], "language": "en", "num_tokens_prompt_total": "0", "num_tokens_generated": "5" }, "properties": { "transcription": { "type": "string", "description": "The complete transcribed text from the audio file" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranscribeSegment" }, "description": "List of transcribed segments with timing information" }, "language": { "type": "string", "description": "The detected language of the transcription, returned as an ISO 639-1 language code such as\n\"en\" for English, \"de\" for German, \"fr\" for French, etc.\nFor information on supported languages, refer to the documentation of the model that you are using.\n" }, "num_tokens_prompt_total": { "type": "integer", "description": "Total number of tokens in the prompt. For many transcription models (e.g., whisper) zero, as the tokenization of the input audio file is not exposed.\n" }, "num_tokens_generated": { "type": "integer", "description": "Total number of tokens generated" } } }, "TranslationSegment": { "type": "object", "properties": { "source": { "type": "string", "description": "The input text to be translated." }, "translation": { "type": "string", "description": "The translated output text of the segment." }, "score": { "type": "number", "description": "Estimate for the overall quality of the translation on a scale of 0 to 1." } } }, "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\nmust be specified using ISO 639 (and RFC 1766) language codes such as \"en\" for English,\n\"de\" for German, \"fr\" for French, etc. For a list of supported languages, refer to the\n`/languages` endpoint.\n" } }, "required": [ "model", "source", "target_language" ] }, "TranslationResponse": { "type": "object", "example": { "translation": "Wie hei\u00dft du?", "score": "0.704557", "segments": "null", "num_tokens_prompt_total": "18", "num_tokens_generated": "0" }, "properties": { "translation": { "type": "string", "description": "The complete translated output text" }, "score": { "type": "number", "description": "Estimate for the overall quality of the translation on a scale of 0 to 1." }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationSegment" }, "description": "List of translated segments", "nullable": "true" }, "num_tokens_prompt_total": { "type": "integer", "description": "Total number of tokens in the prompt.\n" }, "num_tokens_generated": { "type": "integer", "description": "Total number of tokens generated. For translation tasks this will always be zero, as the current translation models don't expose the tokens.\n" } } }, "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" ] }, "RerankResponse": { "type": "object", "example": { "results": [ { "index": "0", "relevance_score": "0.704557" }, { "index": "1", "relevance_score": "0.698765" } ], "usage": { "completion_tokens": "0", "prompt_tokens": "0", "total_tokens": "18" } }, "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The index of the document in the original list of documents." }, "relevance_score": { "type": "number", "description": "The relevance score of the document." } } } }, "usage": { "description": "Usage statistics for the request.", "type": "object", "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "properties": { "completion_tokens": { "description": "Number of tokens in the generated completion. Will always be 0 for rerank tasks.", "type": "integer" }, "prompt_tokens": { "description": "Number of tokens in the prompt. Will always be 0 for rerank tasks.", "type": "integer" }, "total_tokens": { "description": "Total number of tokens used in the request.", "type": "integer" } } } } } } }, "tags": [ { "name": "API description" }, { "name": "tokens", "description": "Manage tokens associated with your user account for API access." }, { "name": "models" }, { "name": "tasks", "description": "Requests for different types of tasks you can request with our models." } ], "paths": { "/version": { "get": { "summary": "Current API version", "description": "Will return the version number of the API that is deployed to this environment.", "operationId": "version", "tags": [ "API description" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string", "example": "1.0.0" } } } } } } }, "/users/me/tokens": { "get": { "summary": "Get issued API tokens", "description": "Will return a list of API tokens that are registered for this user (only token metadata is returned, not the actual tokens)\n", "operationId": "tokens", "tags": [ "tokens" ], "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "example": "token used on my laptop", "description": "A simple description that was supplied when creating the token\n" }, "token_id": { "type": "integer", "description": "The token ID to use when calling other endpoints\n" } }, "required": [ "description", "token_id" ] } } } } } } }, "post": { "summary": "Create a new API token", "description": "Create a new token to authenticate against the API with (the actual API token is only returned when calling this endpoint)\n", "operationId": "newToken", "tags": [ "tokens" ], "security": [ { "token": [] } ], "requestBody": { "required": "true", "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "token used on my laptop", "description": "a simple description to remember the token by\n" } }, "required": [ "description" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "properties": { "description": { "type": "string", "description": "the description you provided" }, "token_id": { "type": "number", "description": "the ID of the API token" } }, "required": [ "description", "token_id" ] }, "token": { "type": "string", "description": "the API token that can be used in the Authorization header" } }, "required": [ "metadata", "token" ] } } } } } } }, "/users/me/tokens/{token_id}": { "parameters": [ { "name": "token_id", "schema": { "type": "integer", "format": "int32" }, "in": "path", "description": "API token ID", "required": "true" } ], "delete": { "summary": "Delete an API token", "operationId": "deleteToken", "tags": [ "tokens" ], "security": [ { "token": [] } ], "responses": { "204": { "description": "No Content" } } } }, "/models/{modelName}/tokenizer": { "parameters": [ { "name": "modelName", "in": "path", "description": "Name of the model", "required": "true", "schema": { "type": "string" } } ], "get": { "operationId": "getModelTokenizer", "summary": "Get the tokenizer of a model", "description": "Returns a representation of the tokenizer that was used to train that model", "tags": [ "models" ], "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/models_available": { "get": { "summary": "Available models (Deprecated)", "deprecated": "true", "description": "Will return all currently available models.", "operationId": "availableModels", "tags": [ "models" ], "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "hostings": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "/model-settings": { "get": { "summary": "Settings of models", "description": "Only models available to the client will be listed.", "operationId": "modelSettings", "tags": [ "models" ], "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "unavailable" ], "description": "The current availability status of the model. Currently supported states are:\n - `available`: The model is configured and a matching worker is connected to serve it.\n - `unavailable`: The model is configured but no worker has shown recent activity to serve it.\n" }, "description": { "type": "string" }, "multimodal": { "type": "boolean", "description": "Feature flag for whether or not multimodal prompts are available to users." }, "max_context_size": { "type": "number", "description": "The maximum context size of this model." }, "semantic_embedding": { "type": "boolean", "description": "True if this model supports semantic embeddings." }, "completion_type": { "type": "string", "enum": [ "none", "full" ], "description": "The completion type supported by the model.\n\n- `none`: The model has not been trained to support completions. Trying to trigger a completion request will lead to a validation error.\n- `full`: The model has been trained to support completions.\n" }, "embedding_type": { "type": "string", "enum": [ "none", "raw", "semantic", "instructable" ], "description": "The embedding type supported by the model.\n\n- `none`: The model cannot be used for embeddings. The scheduler will reject requests for embeddings to this model.\n- `raw`: The model has not explicitly been trained to support embeddings. However, it is possible to retrieve the embedding details technically. This option maps to the `/embed` endpoint.\n- `semantic`: The model has been trained with a switchable set of weights usable for semantic embedding retrieval. This option maps to the `/semantic_embed` endpoint.\n- `instructable`: The model has been trained to support any custom instruction for embedding retrieval. This option maps to the `/instructable_embed` endpoint.\n\nThis flag replaces `semantic_embedding_enabled` and should always be set. If `embedding_type` is unset, `semantic_embedding_enabled` will take control. If both `embedding_type` and `semantic_embedding_enabled` are used, implausible combinations are rejected.\n" }, "aligned": { "type": "boolean", "description": "Specifies whether the model is aligned s.t. end users can be warned about the model's limitations." }, "chat": { "type": "boolean", "description": "True if this model is supported by the chat endpoint." }, "prompt_template": { "type": "string", "description": "A prompt template that can be used for this model." }, "maximum_completion_tokens": { "nullable": "true", "type": "number", "description": "Maximum number of tokens that can be generated by a user request. Not to be confused with the context size which limits the request size including the prompt." }, "model_card": { "nullable": "true", "type": "string", "format": "uri", "description": "Link to further information about the model" } } } } } } } } } }, "/complete": { "post": { "summary": "Completion", "description": "Will complete a prompt using a specific model. To obtain a valid model, use `GET` `/model-settings`.\n", "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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.\nNote: If the max_tokens, i.e., the maximum number of allowed completion tokens is encountered before the completion is finished by the model,\nthen the JSON output will be cut off and therefore invalid.\n\nJSON completion is currently only available for luminous workers.\n\nTo obtain a valid model, use `GET /models_available`.\n", "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\n(e.g. OpenAI) and provides vector representations that can be used for semantic similarity,\nsearch, clustering, recommendations, anomaly detection, and classification tasks.\nTo ensure deployed embedding models support this endpoint, they need to be configured with\n`embedding_task.supported = true` in the model settings.\n", "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\nprompt impacts each token of the completion.\n", "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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" } } } } } } }, "/steering_concepts": { "post": { "summary": "Create a steering concept (BETA)", "description": "Upload a description of a new steering concept, i.e. a list of negative\nand positive examples. This steering concept can then be used in\ncompletion and chat requests to steer the model's answers.\n\nThis request is idempotent. Sending the same steering concept twice will\nreturn the same ID.\n\nNote: This is a BETA feature and might not be available in your\ninstallation of PhariaAI.\n", "operationId": "create_steering_concept", "tags": [ "steering" ], "security": [ { "token": [] } ], "requestBody": { "required": "true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSteeringConceptRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSteeringConceptResponse" } } } } } } }, "/openapi.yaml": { "get": { "summary": "OpenAPI specification", "description": "Returns the latest OpenAPI specification for this API.\n", "tags": [ "API description" ], "responses": { "200": { "description": "OK", "content": { "text/yaml": { "schema": { "type": "string" } } } } } } }, "/users/login": { "post": { "summary": "Login with email and password", "description": "This should not be used by most API consumers, who should generate API tokens using the login page and use bearer authentication.\nThis endpoint allows bootstrapping the API via login to generate more API tokens.\n", "tags": [ "users" ], "requestBody": { "required": "true", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "the email address" }, "password": { "type": "string", "description": "the password" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetail" } } }, "headers": { "Set-Cookie": { "schema": { "type": "string" } } } } } } }, "/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\nabout the task, including duration of execution and cost in credits.\n", "operationId": "recentRequests", "tags": [ "tasks" ], "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentRequestsResponse" } } } } } } }, "/users/me": { "get": { "tags": [ "users" ], "summary": "Get settings for own user", "description": "Returns details of this user. Can be called by a user which has access to this user id or by an admin for any user.\n", "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetail" } } } } } } }, "/check_privileges": { "post": { "operationId": "postCheckPrivileges", "summary": "Check user privileges", "description": "Post an array of permissions as an authenticated users.\nWe return the subset of the posted permissions that have been granted to the user.\n", "tags": [ "permissions" ], "security": [ { "token": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Permissions" } } } } } } }, "/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\n", "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\nby de-prioritizing your request below concurrent ones.\n" } ], "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\na relevance score. To claim that a deployed reranker model supports this endpoint, it needs to be\nconfigured with `rerank_task.supported = true` in the model settings.\n", "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\nby de-prioritizing your request below concurrent ones.\n" } ], "requestBody": { "required": "true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponse" } } } } } } } }, "servers": [ { "url": "{host}/v1", "variables": { "host": { "default": "https://api.pharia.example.com" } } } ] }