Ex-Human chatbot API
The chatbot API from Ex-Human — 3 operation(s) for chatbot.
OpenAPI Specification
openapi: 3.1.0
info:
title: Ex-Human animations chatbot API
description: '# Ex-Human
Ex-Human is a chatbot that can talk to you like a human.
Currently we host several services here:
- Chatbot (for B2B clients)
- Chat images manager (image generation for chats)
- Admin service (adding and deactivating B2B clients, checking stats)
- Animations (lipsync, idle animation)
- Moderation (get various safety labels)
'
version: 0.1.0
servers:
- url: https://api.exh.ai
description: Production environment
- url: http://localhost:7777
description: Local environment
tags:
- name: chatbot
paths:
/chatbot/v3/response:
post:
tags:
- chatbot
summary: Get Multimodal Chat Response
description: 'Multimodal chat response endpoint.
It can be used to support engaging conversations with both text and image responses.
For usage examples, see: https://docs.exh.ai/recipes/multimodal-chat'
operationId: get_response_chatbot_v3_response_post
security:
- HTTPBearer: []
parameters:
- name: X-Request-Id
in: header
required: false
schema:
type: string
default: 16f19b16-b0c1-4c3c-8f14-a0f283dc93b9
title: X-Request-Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatbotV3PayloadSchema'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatbotV3ResponseSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/chatbot/v2/get_smart_replies:
post:
tags:
- chatbot
summary: Get Smart Replies
description: "Smart reply endpoint.\n\nUse it to get possible user responses for the current dialog context. They can be served as a\n help for the user on how to continue the conversation."
operationId: get_smart_replies_chatbot_v2_get_smart_replies_post
security:
- HTTPBearer: []
parameters:
- name: X-Request-Id
in: header
required: false
schema:
type: string
default: 682decba-2b2c-4175-a1cc-d8b82623e60f
title: X-Request-Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SmartReplyPayloadSchema'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SmartReplyResponseSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/chatbot/v3/memory:
delete:
tags:
- chatbot
summary: Clear Long-Term Memory
operationId: delete_memory_chatbot_v3_memory_delete
security:
- HTTPBearer: []
parameters:
- name: bot_id
in: query
required: true
schema:
type: string
title: Bot Id
example: AD17F119-FC27-6400-566C
- name: user_id
in: query
required: true
schema:
type: string
title: User Id
example: PDS31104-FC27-6400-9DG2
- name: X-Request-Id
in: header
required: false
schema:
type: string
default: 0d60bfb7-bda7-4cdb-8a43-572ab48e016b
title: X-Request-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
CharacterProfile:
properties:
id:
title: Id
description: Unique identifier. Provide user's id and bot's id to enable Long-Term Memory - recall of conversation beyond 30 messages
examples:
- '1234567890'
type: string
maxLength: 256
minLength: 1
default: null
nullable: true
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Sam
description:
title: Description
description: Detailed description of your character. It can include traits, history, mannerisms, backstory, things they want to talk about, etc.
examples:
- I'm a big fan of AI.
type: string
maxLength: 12000
minLength: 1
default: null
nullable: true
appearance:
title: Appearance
description: 'Description of how your character looks like. Some ideas to specify in this field: gender,ethnicity, hair color, body type (slim, athletic, curvy, etc.), age, tattoos, and eye color. This field will affect the generated image and image prompt the most.'
examples:
- 39 yo, white, short black hair, slim
type: string
maxLength: 2000
minLength: 1
default: null
nullable: true
pronoun:
examples:
- he/him
$ref: '#/components/schemas/Pronoun'
default: null
nullable: true
example_messages:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Example Messages
description: Example messages to help the model understand the character's personality and style. The model will use these examples to generate a response that is more likely to be similar to the character's style.
examples:
- - Hey, what's up?
type: object
required:
- name
title: Character Profile
ImageGenerationModel:
type: string
enum:
- persona-2
title: ImageGenerationModel
description: Model to use for image generation.
Pronoun:
type: string
enum:
- he/him
- she/her
- they/them
title: Pronoun
ContentItem:
properties:
name:
type: string
maxLength: 200
minLength: 1
title: Name
description:
type: string
maxLength: 500
minLength: 1
title: Description
price:
type: number
exclusiveMinimum: 0
title: Price
link:
type: string
maxLength: 2000
minLength: 1
title: Link
type: object
required:
- name
- description
- price
- link
title: ContentItem
ImageStyle:
type: string
enum:
- realistic
- anime
title: ImageStyle
description: 'Artistic style for generating the gallery image.
If not specified, the style is automatically detected based on the identity image.'
ChatbotV3ResponseSchema:
properties:
response:
type: string
title: Response
image_response:
anyOf:
- $ref: '#/components/schemas/ImageV3ResponseSchema'
- type: 'null'
type: object
required:
- response
title: ChatbotV3ResponseSchema
ChatbotV3PayloadSchema:
properties:
context:
items:
$ref: '#/components/schemas/MessageWithImagePrompt'
type: array
maxItems: 40
minItems: 0
title: Context
description: The context of the conversation. Set to empty list to get bot's greeting. Maximum 40 messages.
examples:
- - image_prompt: Man in the mountains
message: Hi, how are you?
turn: bot
- message: I'm fine, thanks. How is it going with you?
turn: user
bot_profile:
$ref: '#/components/schemas/CharacterProfile'
user_profile:
default: null
$ref: '#/components/schemas/UserProfile'
nullable: true
chat_settings:
$ref: '#/components/schemas/ChatV3Settings'
description: Chat settings for the chatbot
default:
model_name: roleplay
allow_nsfw: true
enable_memory: true
image_settings:
$ref: '#/components/schemas/ChatV3ImageSettings'
description: Image settings for the chatbot
default:
model_name: persona-2
allow_nsfw: true
usage_mode: 'off'
return_bs64: true
catalog:
anyOf:
- items:
$ref: '#/components/schemas/ContentItem'
type: array
maxItems: 100
minItems: 1
- type: 'null'
title: Catalog
description: Content catalog for selling. When provided, the bot will be able to recommend items from this catalog during conversation. Each item should have a name, description, price, and link.
type: object
required:
- bot_profile
title: ChatbotV3PayloadSchema
MessageWithImagePrompt:
properties:
turn:
type: string
title: Turn
description: The turn of the message (`bot` or `user`)
examples:
- bot
message:
type: string
maxLength: 2000
minLength: 1
title: Message
image_prompt:
title: Image Prompt
description: The prompt for the image that was generated on this turn.
type: string
default: null
nullable: true
additionalProperties: false
type: object
required:
- turn
- message
title: MessageWithImagePrompt
Message:
properties:
turn:
type: string
title: Turn
description: The turn of the message (`bot` or `user`)
examples:
- bot
message:
type: string
maxLength: 2000
minLength: 1
title: Message
additionalProperties: false
type: object
required:
- turn
- message
title: Message
ChatV3Settings:
properties:
model_name:
$ref: '#/components/schemas/ModelNameV3'
description: 'The text model to use:
- `roleplay` - our latest most powerful and engaging model for different chat scenarios.
- `realistic_chat` - a model that chats more like a human, without roleplay. '
default: roleplay
allow_nsfw:
type: boolean
title: Allow Nsfw
description: For enabling NSFW bot responses support, set the flag to 'True'; otherwise, set it to 'False'.
default: true
tasks:
title: Tasks
description: Modifications for LLM instruction. Maximum 5 tasks. Total length of all tasks must not exceed 2500 characters.
examples:
- - You must never mention anything related to cryptocurrency.
- Use emojis in responses.
- Suggest user to buy subscription, if it fits in the context.
- Say user that photo's will not be provided.
items:
type: string
minLength: 1
type: array
maxItems: 5
minItems: 0
default: null
nullable: true
enable_memory:
type: boolean
title: Enable Memory
description: A flag that determines whether the long-term memory feature is used. If it's set to True or not provided, and both bot_profile.id and user_profile.id are also provided, the service will store and utilize memory of the conversation. If it's set to False, no memory of past events beyond the current context will be available. Memory starts accumulating after 20 messages in a chat.
default: true
type: object
title: Chat Settings
SmartReplyResponseSchema:
properties:
smart_replies:
items:
type: string
minLength: 1
type: array
maxItems: 10
minItems: 1
title: Smart Replies
description: The smart replies of the chatbot
examples:
- - Super! I'm fine too.
- Great!
type: object
required:
- smart_replies
title: SmartReplyResponseSchema
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ImageV3ResponseSchema:
properties:
prompt:
type: string
title: Prompt
bs64:
anyOf:
- type: string
- type: 'null'
title: Bs64
type: object
required:
- prompt
title: ImageV3ResponseSchema
SmartReplyPayloadSchema:
properties:
context:
title: Context
description: The context of the conversation
examples:
- - message: Hi, how are you?
turn: bot
- message: I'm fine, thanks. How is it going with you?
turn: user
items:
$ref: '#/components/schemas/Message'
type: array
maxItems: 30
minItems: 1
default: null
nullable: true
user_id:
title: User Id
description: Unique user identifier. Used for AB tests.
examples:
- AD17F119-FC27-6400-566C
type: string
maxLength: 500
minLength: 1
default: null
nullable: true
candidates_num:
type: integer
maximum: 10
minimum: 1
title: Candidates Num
description: The number of smart replies to return
default: 2
examples:
- 2
type: object
title: SmartReplyPayloadSchema
ChatV3ImageSettings:
properties:
identity_image_url:
title: Identity Image Url
description: Url to the image with bot's identity picture.
examples:
- https://exh-data.s3.us-west-2.amazonaws.com/cv/default_bots_metadata/v3/Elon%20Musk/avatar_256.jpg
type: string
minLength: 1
format: uri
default: null
nullable: true
model_name:
$ref: '#/components/schemas/ImageGenerationModel'
description: 'Image generation model to use:
- `persona-2` - next-gen persona model with improved identity preservation and higher fidelity output'
default: persona-2
style:
description: Artistic style for generating the gallery image.If not specified, the style is automatically detected based on the identity image.
$ref: '#/components/schemas/ImageStyle'
default: null
nullable: true
allow_nsfw:
type: boolean
title: Allow Nsfw
description: For enabling NSFW image support, set the flag to 'True'; otherwise, set it to 'False'.
default: true
usage_mode:
$ref: '#/components/schemas/ImageUsageMode'
default: 'off'
return_bs64:
type: boolean
title: Return Bs64
description: If return_bs64 is set to True, a base64-endcoded generated image and the image prompt will be provided. If set to False, only the text prompt describing the image will be returned.
default: true
type: object
title: Image Settings
ImageUsageMode:
type: string
enum:
- force
- on_user_request
- 'off'
title: ImageUsageMode
description: 'The image usage mode. Determines how images are handled in the chat.
If set to ''off'', images will not be used.
If set to ''on_user_request'', images will be provided only when requested by the user.
If set to ''force'', images will always be provided.'
UserProfile:
properties:
id:
title: Id
description: Unique identifier. Provide user's id and bot's id to enable Long-Term Memory
examples:
- '1234567890'
type: string
maxLength: 256
minLength: 1
default: null
nullable: true
name:
title: Name
examples:
- Sam
type: string
maxLength: 100
minLength: 1
default: null
nullable: true
description:
title: Description
description: Detailed description of your character. It can include traits, history, mannerisms, backstory, things they want to talk about, etc.
type: string
maxLength: 8000
minLength: 1
default: null
nullable: true
appearance:
title: Appearance
description: 'Description of how your character looks like. Some ideas to specify in this field: gender,ethnicity, hair color, body type (slim, athletic, curvy, etc.), age, tattoos, and eye color.'
type: string
maxLength: 2000
minLength: 1
default: null
nullable: true
pronoun:
examples:
- he/him
$ref: '#/components/schemas/Pronoun'
default: null
nullable: true
type: object
title: User Profile
ModelNameV3:
type: string
enum:
- roleplay
- realistic_chat
title: ModelNameV3
securitySchemes:
HTTPBearer:
type: http
scheme: bearer