CompletionV2Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/scale-ai/json-schema/scale-ai-completion-v2-request-schema.json",
  "title": "CompletionV2Request",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/scale-ai-llm-engine-openapi.yml#/components/schemas/CompletionV2Request",
  "properties": {
    "best_of": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 20.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Best Of",
      "description": "Generates `best_of` completions server-side and returns the \"best\" (the one with the highest log probability per token). Results cannot be streamed.\n\nWhen used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`.\n\n**Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.\n",
      "default": 1
    },
    "top_k": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Top K",
      "description": "Controls the number of top tokens to consider. -1 means consider all tokens."
    },
    "min_p": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Min P",
      "description": "Float that represents the minimum probability for a token to be\n            considered, relative to the probability of the most likely token.\n            Must be in [0, 1]. Set to 0 to disable this."
    },
    "use_beam_search": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Use Beam Search",
      "description": "Whether to use beam search for sampling."
    },
    "length_penalty": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Length Penalty",
      "description": "Float that penalizes sequences based on their length.\n            Used in beam search."
    },
    "repetition_penalty": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Repetition Penalty",
      "description": "Float that penalizes new tokens based on whether\n            they appear in the prompt and the generated text so far. Values > 1\n            encourage the model to use new tokens, while values < 1 encourage\n            the model to repeat tokens."
    },
    "early_stopping": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Early Stopping",
      "description": "Controls the stopping condition for beam search. It\n            accepts the following values: `True`, where the generation stops as\n            soon as there are `best_of` complete candidates; `False`, where an\n            heuristic is applied and the generation stops when is it very\n            unlikely to find better candidates; `\"never\"`, where the beam search\n            procedure only stops when there cannot be better candidates\n            (canonical beam search algorithm)."
    },
    "stop_token_ids": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Stop Token Ids",
      "description": "List of tokens that stop the generation when they are\n            generated. The returned output will contain the stop tokens unless\n            the stop tokens are special tokens."
    },
    "include_stop_str_in_output": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Include Stop Str In Output",
      "description": "Whether to include the stop strings in output text."
    },
    "ignore_eos": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Ignore Eos",
      "description": "Whether to ignore the EOS token and continue generating\n            tokens after the EOS token is generated."
    },
    "min_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Min Tokens",
      "description": "Minimum number of tokens to generate per output sequence\n            before EOS or stop_token_ids can be generated"
    },
    "skip_special_tokens": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Skip Special Tokens",
      "description": "Whether to skip special tokens in the output. Only supported in vllm.",
      "default": true
    },
    "spaces_between_special_tokens": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Spaces Between Special Tokens",
      "description": "Whether to add spaces between special tokens in the output. Only supported in vllm.",
      "default": true
    },
    "add_special_tokens": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Add Special Tokens",
      "description": "If true (the default), special tokens (e.g. BOS) will be added to the prompt."
    },
    "response_format": {
      "anyOf": [
        {
          "$ref": "#/$defs/ResponseFormatText"
        },
        {
          "$ref": "#/$defs/ResponseFormatJsonSchema"
        },
        {
          "$ref": "#/$defs/ResponseFormatJsonObject"
        },
        {
          "type": "null"
        }
      ],
      "title": "Response Format",
      "description": "Similar to chat completion, this parameter specifies the format of output. Only {'type': 'json_object'} or {'type': 'text' } is supported."
    },
    "guided_json": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Guided Json",
      "description": "JSON schema for guided decoding. Only supported in vllm."
    },
    "guided_regex": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Guided Regex",
      "description": "Regex for guided decoding. Only supported in vllm."
    },
    "guided_choice": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Guided Choice",
      "description": "Choices for guided decoding. Only supported in vllm."
    },
    "guided_grammar": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Guided Grammar",
      "description": "Context-free grammar for guided decoding. Only supported in vllm."
    },
    "guided_decoding_backend": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Guided Decoding Backend",
      "description": "If specified, will override the default guided decoding backend of the server for this specific request. If set, must be either 'outlines' / 'lm-format-enforcer'"
    },
    "guided_whitespace_pattern": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Guided Whitespace Pattern",
      "description": "If specified, will override the default whitespace pattern for guided json decoding."
    },
    "model": {
      "type": "string",
      "title": "Model",
      "description": "ID of the model to use."
    },
    "prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "$ref": "#/$defs/Prompt"
        },
        {
          "$ref": "#/$defs/Prompt1"
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt",
      "description": "The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.\n\nNote that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.\n"
    },
    "echo": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Echo",
      "description": "Echo back the prompt in addition to the completion\n",
      "default": false
    },
    "frequency_penalty": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 2.0,
          "minimum": -2.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Frequency Penalty",
      "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.\n\n[See more information about frequency and presence penalties.](/docs/guides/text-generation)\n",
      "default": 0
    },
    "logit_bias": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "integer"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Logit Bias",
      "description": "Modify the likelihood of specified tokens appearing in the completion.\n\nAccepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.\n\nAs an example, you can pass `{\"50256\": -100}` to prevent the <|endoftext|> token from being generated.\n"
    },
    "logprobs": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 5.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Logprobs",
      "description": "Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.\n\nThe maximum value for `logprobs` is 5.\n"
    },
    "max_tokens": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Tokens",
      "description": "The maximum number of [tokens](/tokenizer) that can be generated in the completion.\n\nThe token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.\n",
      "default": 16
    },
    "n": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 128.0,
          "minimum": 1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "N",
      "description": "How many completions to generate for each prompt.\n\n**Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.\n",
      "default": 1
    },
    "presence_penalty": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 2.0,
          "minimum": -2.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Presence Penalty",
      "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.\n\n[See more information about frequency and presence penalties.](/docs/guides/text-generation)\n",
      "default": 0
    },
    "seed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Seed",
      "description": "If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.\n\nDeterminism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.\n"
    },
    "stop": {
      "anyOf": [
        {
          "$ref": "#/$defs/StopConfiguration"
        },
        {
          "type": "null"
        }
      ]
    },
    "stream": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Stream",
      "description": "If set, partial message deltas will be sent. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions).\n",
      "default": false
    },
    "stream_options": {
      "anyOf": [
        {
          "$ref": "#/$defs/ChatCompletionStreamOptions"
        },
        {
          "type": "null"
        }
      ]
    },
    "suffix": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Suffix",
      "description": "The suffix that comes after a completion of inserted text.\n\nThis parameter is only supported for `gpt-3.5-turbo-instruct`.\n"
    },
    "temperature": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 2.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Temperature",
      "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.\n\nWe generally recommend altering this or `top_p` but not both.\n",
      "default": 1
    },
    "top_p": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Top P",
      "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.\n\nWe generally recommend altering this or `temperature` but not both.\n",
      "default": 1
    },
    "user": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "User",
      "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).\n"
    }
  },
  "type": "object",
  "required": [
    "model",
    "prompt"
  ],
  "$defs": {
    "ChatCompletionStreamOptions": {
      "properties": {
        "include_usage": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Include Usage",
          "description": "If set, an additional chunk will be streamed before the `data: [DONE]`\nmessage. The `usage` field on this chunk shows the token usage statistics\nfor the entire request, and the `choices` field will always be an empty\narray. \n\nAll other chunks will also include a `usage` field, but with a null\nvalue. **NOTE:** If the stream is interrupted, you may not receive the\nfinal usage chunk which contains the total token usage for the request.\n"
        }
      },
      "type": "object",
      "title": "ChatCompletionStreamOptions"
    },
    "JsonSchema": {
      "properties": {
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description",
          "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format.\n"
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.\n"
        },
        "schema": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResponseFormatJsonSchemaSchema"
            },
            {
              "type": "null"
            }
          ]
        },
        "strict": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Strict",
          "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`. To learn more, read the [Structured Outputs\nguide](/docs/guides/structured-outputs).\n",
          "default": false
        }
      },
      "type": "object",
      "required": [
        "name"
      ],
      "title": "JsonSchema"
    },
    "Prompt": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array",
          "minItems": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt",
      "description": "The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.\n\nNote that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.\n",
      "default": "<|endoftext|>"
    },
    "Prompt1": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Prompt1Item"
          },
          "type": "array",
          "minItems": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompt1",
      "description": "The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.\n\nNote that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.\n",
      "default": "<|endoftext|>"
    },
    "Prompt1Item": {
      "items": {
        "type": "integer"
      },
      "type": "array",
      "minItems": 1,
      "title": "Prompt1Item"
    },
    "ResponseFormatJsonObject": {
      "properties": {
        "type": {
          "type": "string",
          "const": "json_object",
          "title": "Type",
          "description": "The type of response format being defined. Always `json_object`."
        }
      },
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ResponseFormatJsonObject"
    },
    "ResponseFormatJsonSchema": {
      "properties": {
        "type": {
          "type": "string",
          "const": "json_schema",
          "title": "Type",
          "description": "The type of response format being defined. Always `json_schema`."
        },
        "json_schema": {
          "$ref": "#/$defs/JsonSchema",
          "title": "JSON schema",
          "description": "Structured Outputs configuration options, including a JSON Schema.\n"
        }
      },
      "type": "object",
      "required": [
        "type",
        "json_schema"
      ],
      "title": "ResponseFormatJsonSchema"
    },
    "ResponseFormatJsonSchemaSchema": {
      "properties": {},
      "additionalProperties": true,
      "type": "object",
      "title": "ResponseFormatJsonSchemaSchema"
    },
    "ResponseFormatText": {
      "properties": {
        "type": {
          "type": "string",
          "const": "text",
          "title": "Type",
          "description": "The type of response format being defined. Always `text`."
        }
      },
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ResponseFormatText"
    },
    "StopConfiguration": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/$defs/StopConfiguration1"
        },
        {
          "type": "null"
        }
      ],
      "title": "StopConfiguration",
      "description": "Not supported with latest reasoning models `o3` and `o4-mini`.\n\nUp to 4 sequences where the API will stop generating further tokens. The\nreturned text will not contain the stop sequence.\n"
    },
    "StopConfiguration1": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 4,
          "minItems": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "StopConfiguration1",
      "description": "Not supported with latest reasoning models `o3` and `o4-mini`.\n\nUp to 4 sequences where the API will stop generating further tokens. The\nreturned text will not contain the stop sequence.\n"
    }
  }
}