openapi: 3.1.0
info:
  title: Convai Character Characters Interaction API
  version: '1.0'
  description: 'REST API for creating, listing, updating, cloning, and deleting Convai

    conversational AI characters. Characters are reusable conversational agents

    with backstory, voice, personality, language, and knowledge configuration

    that can be embodied in games, virtual worlds, and 3D experiences via the

    Unity, Unreal, Web, and other Convai SDKs.

    '
  contact:
    name: Convai Developer Support
    url: https://forum.convai.com
servers:
- url: https://api.convai.com
  description: Convai REST API
security:
- ConvaiApiKey: []
tags:
- name: Interaction
paths:
  /character/getResponse:
    post:
      summary: Get Character Response
      operationId: getCharacterResponse
      tags:
      - Interaction
      description: 'Send user input to a Convai character and receive its conversational

        response. Supports text and audio input, with audio, text, action, and

        emotion outputs. Use sessionID="-1" to start a new conversation.

        '
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/GetResponseRequest'
      responses:
        '200':
          description: Character response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponseResponse'
components:
  schemas:
    GetResponseRequest:
      type: object
      required:
      - userText
      - charID
      - sessionID
      - voiceResponse
      properties:
        userText:
          type: string
          description: User input as text. Use "(USER_PERFORMED_ACTIONS)" placeholder when sending audio.
        charID:
          type: string
        sessionID:
          type: string
          description: Use "-1" to start a new session
        voiceResponse:
          type: boolean
          description: Whether to include audio in the response
        file:
          type: string
          format: binary
          description: Optional audio file (wav) for voice input
    GetResponseResponse:
      type: object
      properties:
        text:
          type: string
          description: Character text reply
        audio:
          type: string
          format: byte
          description: Base64-encoded audio response
        sessionID:
          type: string
        action:
          type: string
        emotion:
          type: string
        narrativeSectionId:
          type: string
  securitySchemes:
    ConvaiApiKey:
      type: apiKey
      in: header
      name: CONVAI-API-KEY