Helicone Playground API

openapi: 3.2.0
info:
  title: helicone-api Agent Playground API
  version: 1.0.0
  license:
    name: MIT
  contact: {}
servers:
- url: https://api.helicone.ai/
- url: http://localhost:8585/
tags:
- name: Playground
paths:
  /v1/playground/generate:
    post:
      operationId: Generate
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_ChatCompletion-or-_content-string--reasoning-string--calls-any_.string_'
      tags:
      - Playground
      security:
      - api_key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OpenAIChatRequest'
              - properties:
                  logRequest:
                    type: boolean
                  useAIGateway:
                    type: boolean
                type: object
  /v1/playground/requests-through-helicone:
    post:
      operationId: RequestsThroughHelicone
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_string.string_'
      tags:
      - Playground
      security:
      - api_key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                requestsThroughHelicone:
                  type: boolean
              required:
              - requestsThroughHelicone
              type: object
    get:
      operationId: GetRequestsThroughHelicone
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_boolean.string_'
      tags:
      - Playground
      security:
      - api_key: []
      parameters: []
components:
  schemas:
    Record_string.string_:
      properties: {}
      additionalProperties:
        type: string
      type: object
      description: Construct a type with a set of properties K of type T
    CompletionUsage.CompletionTokensDetails:
      description: Breakdown of tokens used in a completion.
      properties:
        accepted_prediction_tokens:
          type: number
          format: double
          description: 'When using Predicted Outputs, the number of tokens in the prediction that

            appeared in the completion.'
        audio_tokens:
          type: number
          format: double
          description: Audio input tokens generated by the model.
        reasoning_tokens:
          type: number
          format: double
          description: Tokens generated by the model for reasoning.
        rejected_prediction_tokens:
          type: number
          format: double
          description: 'When using Predicted Outputs, the number of tokens in the prediction that did

            not appear in the completion. However, like reasoning tokens, these tokens are

            still counted in the total completion tokens for purposes of billing, output,

            and context window limits.'
      type: object
      additionalProperties: false
    ResultSuccess_ChatCompletion-or-_content-string--reasoning-string--calls-any__:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/ChatCompletion'
          - properties:
              calls: {}
              reasoning:
                type: string
              content:
                type: string
            required:
            - calls
            - reasoning
            - content
            type: object
        error:
          type:
          - number
          - 'null'
          enum:
          - null
      required:
      - data
      - error
      type: object
      additionalProperties: false
    ChatCompletionMessageCustomToolCall.Custom:
      description: The custom tool that the model called.
      properties:
        input:
          type: string
          description: The input for the custom tool call generated by the model.
        name:
          type: string
          description: The name of the custom tool to call.
      required:
      - input
      - name
      type: object
      additionalProperties: false
    OpenAIChatRequest:
      description: Simplified interface for the OpenAI Chat request format
      properties:
        model:
          type: string
        messages:
          items:
            properties:
              tool_calls:
                items:
                  properties:
                    type:
                      type: string
                      enum:
                      - function
                    function:
                      properties:
                        arguments:
                          type: string
                        name:
                          type: string
                      required:
                      - arguments
                      - name
                      type: object
                    id:
                      type: string
                  required:
                  - type
                  - function
                  - id
                  type: object
                type: array
              tool_call_id:
                type: string
              name:
                type: string
              content:
                anyOf:
                - type: string
                - items:
                    properties:
                      image_url:
                        properties:
                          url:
                            type: string
                        required:
                        - url
                        type: object
                      text:
                        type: string
                      type:
                        type: string
                    required:
                    - type
                    type: object
                  type: array
              role:
                type: string
            required:
            - content
            - role
            type: object
          type: array
        temperature:
          type: number
          format: double
        top_p:
          type: number
          format: double
        max_tokens:
          type: number
          format: double
        max_completion_tokens:
          type: number
          format: double
        stream:
          type: boolean
        stop:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
        tools:
          items:
            properties:
              function:
                properties:
                  strict:
                    type: boolean
                  parameters:
                    $ref: '#/components/schemas/Record_string.any_'
                  description:
                    type: string
                  name:
                    type: string
                required:
                - name
                type: object
              type:
                type: string
                enum:
                - function
            required:
            - function
            - type
            type: object
          type: array
        tool_choice:
          anyOf:
          - properties:
              function:
                properties:
                  name:
                    type: string
                  type:
                    type: string
                    enum:
                    - function
                required:
                - name
                - type
                type: object
              type:
                type: string
            required:
            - type
            type: object
          - type: string
            enum:
            - none
            - auto
            - required
        parallel_tool_calls:
          type: boolean
        reasoning_effort:
          type: string
          enum:
          - minimal
          - low
          - medium
          - high
        verbosity:
          type: string
          enum:
          - low
          - medium
          - high
        frequency_penalty:
          type: number
          format: double
        presence_penalty:
          type: number
          format: double
        logit_bias:
          $ref: '#/components/schemas/Record_string.number_'
        logprobs:
          type: boolean
        top_logprobs:
          type: number
          format: double
        n:
          type: number
          format: double
        modalities:
          items:
            type: string
          type: array
        prediction: {}
        audio: {}
        response_format:
          properties:
            json_schema: {}
            type:
              type: string
          required:
          - type
          type: object
        seed:
          type: number
          format: double
        service_tier:
          type: string
        store:
          type: boolean
        stream_options: {}
        metadata:
          $ref: '#/components/schemas/Record_string.string_'
        user:
          type: string
        function_call:
          anyOf:
          - type: string
          - properties:
              name:
                type: string
            required:
            - name
            type: object
        functions:
          items: {}
          type: array
      type: object
      additionalProperties: false
    CompletionUsage.PromptTokensDetails:
      description: Breakdown of tokens used in the prompt.
      properties:
        audio_tokens:
          type: number
          format: double
          description: Audio input tokens present in the prompt.
        cached_tokens:
          type: number
          format: double
          description: Cached tokens present in the prompt.
      type: object
      additionalProperties: false
    ChatCompletionMessageToolCall:
      anyOf:
      - $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall'
      - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall'
      description: A call to a function tool created by the model.
    Record_string.any_:
      properties: {}
      additionalProperties: {}
      type: object
      description: Construct a type with a set of properties K of type T
    ChatCompletionMessage.Annotation.URLCitation:
      description: A URL citation when using web search.
      properties:
        end_index:
          type: number
          format: double
          description: The index of the last character of the URL citation in the message.
        start_index:
          type: number
          format: double
          description: The index of the first character of the URL citation in the message.
        title:
          type: string
          description: The title of the web resource.
        url:
          type: string
          description: The URL of the web resource.
      required:
      - end_index
      - start_index
      - title
      - url
      type: object
      additionalProperties: false
    ChatCompletionMessageFunctionToolCall:
      description: A call to a function tool created by the model.
      properties:
        id:
          type: string
          description: The ID of the tool call.
        function:
          $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall.Function'
          description: The function that the model called.
        type:
          type: string
          enum:
          - function
          description: The type of the tool. Currently, only `function` is supported.
      required:
      - id
      - function
      - type
      type: object
      additionalProperties: false
    ResultSuccess_string_:
      properties:
        data:
          type: string
        error:
          type:
          - number
          - 'null'
          enum:
          - null
      required:
      - data
      - error
      type: object
      additionalProperties: false
    ResultError_string_:
      properties:
        data:
          type:
          - number
          - 'null'
          enum:
          - null
        error:
          type: string
      required:
      - data
      - error
      type: object
      additionalProperties: false
    ChatCompletionMessageCustomToolCall:
      description: A call to a custom tool created by the model.
      properties:
        id:
          type: string
          description: The ID of the tool call.
        custom:
          $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall.Custom'
          description: The custom tool that the model called.
        type:
          type: string
          enum:
          - custom
          description: The type of the tool. Always `custom`.
      required:
      - id
      - custom
      - type
      type: object
      additionalProperties: false
    ResultSuccess_boolean_:
      properties:
        data:
          type: boolean
        error:
          type:
          - number
          - 'null'
          enum:
          - null
      required:
      - data
      - error
      type: object
      additionalProperties: false
    CompletionUsage:
      description: Usage statistics for the completion request.
      properties:
        completion_tokens:
          type: number
          format: double
          description: Number of tokens in the generated completion.
        prompt_tokens:
          type: number
          format: double
          description: Number of tokens in the prompt.
        total_tokens:
          type: number
          format: double
          description: Total number of tokens used in the request (prompt + completion).
        completion_tokens_details:
          $ref: '#/components/schemas/CompletionUsage.CompletionTokensDetails'
          description: Breakdown of tokens used in a completion.
        prompt_tokens_details:
          $ref: '#/components/schemas/CompletionUsage.PromptTokensDetails'
          description: Breakdown of tokens used in the prompt.
      required:
      - completion_tokens
      - prompt_tokens
      - total_tokens
      type: object
      additionalProperties: false
    ChatCompletion:
      description: 'Represents a chat completion response returned by model, based on the provided

        input.'
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        choices:
          items:
            $ref: '#/components/schemas/ChatCompletion.Choice'
          type: array
          description: 'A list of chat completion choices. Can be more than one if `n` is greater

            than 1.'
        created:
          type: number
          format: double
          description: The Unix timestamp (in seconds) of when the chat completion was created.
        model:
          type: string
          description: The model used for the chat completion.
        object:
          type: string
          enum:
          - chat.completion
          description: The object type, which is always `chat.completion`.
        service_tier:
          type:
          - string
          - 'null'
          enum:
          - auto
          - default
          - flex
          - scale
          - priority
          - null
          description: "Specifies the processing type used for serving the request.\n\n- If set to 'auto', then the request will be processed with the service tier\n  configured in the Project settings. Unless otherwise configured, the Project\n  will use 'default'.\n- If set to 'default', then the request will be processed with the standard\n  pricing and performance for the selected model.\n- If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or\n  'priority', then the request will be processed with the corresponding service\n  tier. [Contact sales](https://openai.com/contact-sales) to learn more about\n  Priority processing.\n- When not set, the default behavior is 'auto'.\n\nWhen the `service_tier` parameter is set, the response body will include the\n`service_tier` value based on the processing mode actually used to serve the\nrequest. This response value may be different from the value set in the\nparameter."
        system_fingerprint:
          type: string
          description: 'This fingerprint represents the backend configuration that the model runs with.


            Can be used in conjunction with the `seed` request parameter to understand when

            backend changes have been made that might impact determinism.'
        usage:
          $ref: '#/components/schemas/CompletionUsage'
          description: Usage statistics for the completion request.
      required:
      - id
      - choices
      - created
      - model
      - object
      type: object
      additionalProperties: false
    ChatCompletionAudio:
      description: 'If the audio output modality is requested, this object contains data about the

        audio response from the model.

        [Learn more](https://platform.openai.com/docs/guides/audio).'
      properties:
        id:
          type: string
          description: Unique identifier for this audio response.
        data:
          type: string
          description: 'Base64 encoded audio bytes generated by the model, in the format specified in

            the request.'
        expires_at:
          type: number
          format: double
          description: 'The Unix timestamp (in seconds) for when this audio response will no longer be

            accessible on the server for use in multi-turn conversations.'
        transcript:
          type: string
          description: Transcript of the audio generated by the model.
      required:
      - id
      - data
      - expires_at
      - transcript
      type: object
      additionalProperties: false
    Result_boolean.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_boolean_'
      - $ref: '#/components/schemas/ResultError_string_'
    ChatCompletionMessage.FunctionCall:
      properties:
        arguments:
          type: string
          description: 'The arguments to call the function with, as generated by the model in JSON

            format. Note that the model does not always generate valid JSON, and may

            hallucinate parameters not defined by your function schema. Validate the

            arguments in your code before calling your function.'
        name:
          type: string
          description: The name of the function to call.
      required:
      - arguments
      - name
      type: object
      additionalProperties: false
      deprecated: true
    ChatCompletionMessage:
      description: A chat completion message generated by the model.
      properties:
        content:
          type:
          - string
          - 'null'
          description: The contents of the message.
        refusal:
          type:
          - string
          - 'null'
          description: The refusal message generated by the model.
        role:
          type: string
          enum:
          - assistant
          description: The role of the author of this message.
        annotations:
          items:
            $ref: '#/components/schemas/ChatCompletionMessage.Annotation'
          type: array
          description: 'Annotations for the message, when applicable, as when using the

            [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).'
        audio:
          allOf:
          - $ref: '#/components/schemas/ChatCompletionAudio'
          description: 'If the audio output modality is requested, this object contains data about the

            audio response from the model.

            [Learn more](https://platform.openai.com/docs/guides/audio).'
        function_call:
          allOf:
          - $ref: '#/components/schemas/ChatCompletionMessage.FunctionCall'
          deprecated: true
        tool_calls:
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCall'
          type: array
          description: The tool calls generated by the model, such as function calls.
      required:
      - content
      - refusal
      - role
      type: object
      additionalProperties: false
    Result_ChatCompletion-or-_content-string--reasoning-string--calls-any_.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_ChatCompletion-or-_content-string--reasoning-string--calls-any__'
      - $ref: '#/components/schemas/ResultError_string_'
    ChatCompletion.Choice:
      properties:
        finish_reason:
          type: string
          enum:
          - stop
          - length
          - tool_calls
          - content_filter
          - function_call
          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, `length` if the maximum

            number of tokens specified in the request was reached, `content_filter` if

            content was omitted due to a flag from our content filters, `tool_calls` if the

            model called a tool, or `function_call` (deprecated) if the model called a

            function.'
        index:
          type: number
          format: double
          description: The index of the choice in the list of choices.
        logprobs:
          allOf:
          - $ref: '#/components/schemas/ChatCompletion.Choice.Logprobs'
          description: Log probability information for the choice.
        message:
          $ref: '#/components/schemas/ChatCompletionMessage'
          description: A chat completion message generated by the model.
      required:
      - finish_reason
      - index
      - logprobs
      - message
      type: object
      additionalProperties: false
    ChatCompletion.Choice.Logprobs:
      description: Log probability information for the choice.
      properties:
        content:
          items:
            $ref: '#/components/schemas/ChatCompletionTokenLogprob'
          type:
          - array
          - 'null'
          description: A list of message content tokens with log probability information.
        refusal:
          items:
            $ref: '#/components/schemas/ChatCompletionTokenLogprob'
          type:
          - array
          - 'null'
          description: A list of message refusal tokens with log probability information.
      required:
      - content
      - refusal
      type: object
      additionalProperties: false
    Record_string.number_:
      properties: {}
      additionalProperties:
        type: number
        format: double
      type: object
      description: Construct a type with a set of properties K of type T
    ChatCompletionMessageFunctionToolCall.Function:
      description: The function that the model called.
      properties:
        arguments:
          type: string
          description: 'The arguments to call the function with, as generated by the model in JSON

            format. Note that the model does not always generate valid JSON, and may

            hallucinate parameters not defined by your function schema. Validate the

            arguments in your code before calling your function.'
        name:
          type: string
          description: The name of the function to call.
      required:
      - arguments
      - name
      type: object
      additionalProperties: false
    ChatCompletionTokenLogprob:
      properties:
        token:
          type: string
          description: The token.
        bytes:
          items:
            type: number
            format: double
          type:
          - array
          - 'null'
          description: 'A list of integers representing the UTF-8 bytes representation of the token.

            Useful in instances where characters are represented by multiple tokens and

            their byte representations must be combined to generate the correct text

            representation. Can be `null` if there is no bytes representation for the token.'
        logprob:
          type: number
          format: double
          description: 'The log probability of this token, if it is within the top 20 most likely

            tokens. Otherwise, the value `-9999.0` is used to signify that the token is very

            unlikely.'
        top_logprobs:
          items:
            $ref: '#/components/schemas/ChatCompletionTokenLogprob.TopLogprob'
          type: array
          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.'
      required:
      - token
      - bytes
      - logprob
      - top_logprobs
      type: object
      additionalProperties: false
    ChatCompletionMessage.Annotation:
      description: A URL citation when using web search.
      properties:
        type:
          type: string
          enum:
          - url_citation
          description: The type of the URL citation. Always `url_citation`.
        url_citation:
          $ref: '#/components/schemas/ChatCompletionMessage.Annotation.URLCitation'
          description: A URL citation when using web search.
      required:
      - type
      - url_citation
      type: object
      additionalProperties: false
    ChatCompletionTokenLogprob.TopLogprob:
      properties:
        token:
          type: string
          description: The token.
        bytes:
          items:
            type: number
            format: double
          type:
          - array
          - 'null'
          description: 'A list of integers representing the UTF-8 bytes representation of the token.

            Useful in instances where characters are represented by multiple tokens and

            their byte representations must be combined to generate the correct text

            representation. Can be `null` if there is no bytes representation for the token.'
        logprob:
          type: number
          format: double
          description: 'The log probability of this token, if it is within the top 20 most likely

            tokens. Otherwise, the value `-9999.0` is used to signify that the token is very

            unlikely.'
      required:
      - token
      - bytes
      - logprob
      type: object
      additionalProperties: false
    Result_string.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_string_'
      - $ref: '#/components/schemas/ResultError_string_'
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: 'Bearer token authentication. Format: ''Bearer YOUR_API_KEY'''