AI chatbots
Custom chatbots
AI image bots
Contact us · About · API

API Reference - ChatbotsPlace API

Table of Contents

API Authorization

In order to use ChatbotsPlace API, you must first create an API key. Do NOT share you API key with people.

Once you have obtained an API key, you can authenticate to the APIs below using the Authorization request header as followed:

Authorization: Bearer {API_key}

POST /api/public/chat (Send chat request)

Send a chat message to our chatbot. This operation is can be synchronous or asynchronous. By default, this operation is asynchronous, and you can retrieve the chatbot response using the messageId in the response. If you set wait: true, then this operation will be synchronous, and it will wait until the chatbot response is ready before returning.

Please note that there are different versions of our chatbot. Each has a different price and context length. Refers to the version pricing table below for more details. The cost of the API will be returned in the response as well.

Passing in the same conversationId will allow users to continue the previous conversation. However, if the conversation length exceeds the max context length available for the selected chatbot version, the older messages in the conversation will be dropped. If you do not pass in a conversationId, a random one will be generated for you.

Messages in a conversation will be retained on ChatbotsPlace for 90 days. Afterward, they will be automatically removed.

POST Body
name type data type description
message required string The user message to send to chatbot.
version required string chatbot version. Accepted values are "v3.5", "v3.5_16K", "v4.0_sm", and "v4.0"
wait optional boolean If true, wait for the chat response to finish before returning. Otherwise, this will return a messageId that can be used to retrieve the chat response later using the GET /api/public/chat API.
conversationId optional string The conversation ID. Leave blank to generate a random one.
systemMessage optional string System message helps set the behavior of the assistant. For example, you can modify the personality of the assistant or provide specific instructions about how it should behave throughout the conversation.
temperature optional number 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.
Responses
http code content-type response
200 application/json {"messageId": "abcd-1234", "cost": 1, "conversationId": "efgh-6789"}
400 text/plain The request is invalid. Please make sure that the POST body is correct.
401 text/plain Invalid API key
403 text/plain Insufficient gems
Example cURL
 curl -X POST -H "Content-Type: application/json" --data @post.json https://chatbotsplace.com/api/public/chat
Example Javascript
async function run() {
  const { data } = await axios.post(
    `https://chatbotsplace.com/api/public/chat`,
    {
      version: 'v3.5',
      message: 'Tell me a joke',
      wait: true
    },
    {
      headers: {
        authorization: `Bearer ${apiKey}`
      }
    }
  );
  console.log(data);
}
Example Python
import requests
import json

apiKey = '<your-api-key>'  # Define your apiKey

headers = {
    'content-type': 'application/json',
    'authorization': f'Bearer {apiKey}'
}

data_post = {
    'version': 'v3.5',
    'message': 'Tell me a joke',
    'wait': True
}
response = requests.post('https://chatbotsplace.com/api/public/chat', headers=headers, json=data_post)

data = response.json()
print(data)

GET /api/public/chat (Retrieve chat response)

Retrieve the chat response. This operation is free to call.

The chatbot response may not be finished when this API returns. You may check the isFinished boolean field in the response to figure out if the chatbot response is complete. Even if isFinished is false, the message field may be partially filled in, allowing you to show a partial response to the user. However, we recommend that you wait at least 1 second between each call to this API to avoid overloading our system.

If the chatbot failed to respond, isError field will be set to true. If the failure is due to the chatbot getting too many requests, then the tooManyRequests field will be set to true. In most cases, ChatbotsPlace will catch the error and refund the gems spent at the beginning of the POST request. If so, isRefunded field will be set to true.

isFinished field will be set to true either when the chatbot's response is complete or when there is an error. Calling this API again after isFinished is true will return the same result.

A messageId may be used to retrieve chat response for up to 5 minutes. Afterward, this API may return an empty response.

Parameters
name type data type description
messageId required string messageId from the POST request in order to retrieve the chat repsonse.
Responses
http code content-type response
200 application/json { "message": "chatbot response", "isFinished": true, "isError": false, "tooManyRequests": false, "isRefunded": false }
Example cURL
 curl -X GET -H "Content-Type: application/json" https://chatbotsplace.com/api/public/chat?messageId=abcd-1234
Example Javascript
async function run() {
  const { data } = await axios.post(
    `https://chatbotsplace.com/api/public/chat`,
    {
      version: 'v3.5',
      message: 'Tell me a joke'
    },
    {
      headers: {
        authorization: `Bearer ${apiKey}`
      }
    }
  );
  while (true) {
    const getRes = await fetch(
      `https://chatbotsplace.com/api/public/chat?messageId=${data.messageId}`
    );
    const botMessage = await getRes.json();
    if (botMessage.isFinished) {
      console.log('Final message:', botMessage.message);
      return;
    }
    console.log('Partial message:', botMessage.message);
    await delay(2000);
  }
}
Example Python
import requests
import json
import time

apiKey = '<your-api-key>'  # Define your apiKey

headers = {
    'content-type': 'application/json',
    'authorization': f'Bearer {apiKey}'
}

def run():
    session = requests.Session()

    # Post request
    url_post = 'https://chatbotsplace.com/api/public/chat'
    data_post = {
        'version': 'v3.5',
        'message': 'Tell me a joke'
    }
    response = session.post(url_post, headers=headers, json=data_post)

    data = response.json()

    while True:
        url_get = f'https://chatbotsplace.com/api/public/chat?messageId={data.get("messageId")}'
        response_get = session.get(url_get, headers=headers)
        bot_message = response_get.json()

        # Check if it is finished
        if bot_message.get('isFinished'):
            print('Final message:', bot_message.get('message'))
            return
        print('Partial message:', bot_message.get('message'))

        # Sleep for 2 seconds before next call
        time.sleep(2)

run()

POST /api/public/art (Generate AI image)

Generate an image using AI. Each generated image costs 1 💎.

POST Body
name type data type description
message required string The prompt for generating the image.
version required string AI version to use. Accepted values are "sdxl" (for Stable Diffusion), "dalle" (for OpenAI's DALL·E)
n optional number Number of images to generate. Default to 1. Each image costs 1 💎.
width optional number The width of the image. For "sdxl", the supported dimensions are: 512x512, 768x512, 512x768, 640x512, 512x640, 896x512, 512x896. For "dalle", the supported dimensions are: 256x256, 512x512, 1024x1024.
height optional number The height of the image. For "sdxl", the supported dimensions are: 512x512, 768x512, 512x768, 640x512, 512x640, 896x512, 512x896. For "dalle", the supported dimensions are: 256x256, 512x512, 1024x1024.
stylePreset required string For "sdxl" only. Supported values are '3d-model', 'analog-film', 'anime', 'cinematic', 'comic-book', 'digital-art', 'enhance', 'fantasy-art', 'isometric', 'line-art', 'low-poly', 'modeling-compound', 'neon-punk', 'origami', 'photographic', 'pixel-art'.
Responses
http code content-type response
200 application/json { "cost": 1, "botImages": [{ "id": "v2-333c2a85-ca12-42d0-b234-8330dbc5ce34", "isNsfw": false, "prompt": "a lady", "thumbnailUrl": "https://images.chatbotsplace.com/thumbnail/v2-333c2a85-ca12-42d0-b234-8330dbc5ce34.png", "largeUrl": "https://images.chatbotsplace.com/full/v2-333c2a85-ca12-42d0-b234-8330dbc5ce34.png" }]
400 text/plain The request is invalid. Please make sure that the POST body is correct.
401 text/plain Invalid API key
403 text/plain Insufficient gems
Example cURL
 curl -X POST -H "Content-Type: application/json" --data @post.json https://chatbotsplace.com/api/public/art
Example Javascript
async function run() {
  const { data } = await axios.post(
    `https://chatbotsplace.com/api/public/art`,
    {
      version: 'sdxl',
      message: 'a pretty girl'
    },
    {
      headers: {
        authorization: `Bearer ${apiKey}`
      }
    }
  );
  console.log(data);
}
Example Python
import requests
import json

apiKey = '<your-api-key>'  # Define your apiKey

headers = {
    'content-type': 'application/json',
    'authorization': f'Bearer {apiKey}'
}

data_post = {
    'version': 'sdxl',
    'message': 'a pretty girl'
}
response = requests.post('https://chatbotsplace.com/api/public/art', headers=headers, json=data_post)

data = response.json()
print(data)

POST /api/public/tts/standard (Text-to-speech with standard voice)

Convert text into synthesized speech using standard voice. Standard TTS voices use concatenative synthesis. This method strings together the phonemes of recorded speech. This results in lower price at the expense of lower speech quality. For better speech quality, consider using /api/public/tts/neural API.

The cost for this API is 0.025 💎 for 100 characters (rounded up to the next 100 characters). 1 gem can produce up to 4000 characters. Currently, the maximum message length is 3000 characters. Please contact us if you need a higher limit.

Refers to the Standard TTS voices table table for a list of voices and languages available.

POST Body
name type data type description
message required string The message to synthesize into speech.
voiceId optional string The ID of the voice to use to synthesize this message (e.g., "aws-en-US-Joanna"). Either voiceId or the language must be specified.
language optional string The language used to synthesize this message (e.g., "en-US"). Either voiceId or the language must be specified.
gender optional string The gender of the voice to use for this message. Only used if language is specified.
Responses
http code content-type response
200 audio/mp3 Synthesized audio stream
400 text/plain The request is invalid. Please make sure that the POST body is correct.
401 text/plain Invalid API key
403 text/plain Insufficient gems
Example cURL
 curl -X POST -H "Content-Type: application/json" --data @post.json https://chatbotsplace.com/api/public/tts/standard
Example Javascript
async function run() {
  const { data } = await axios.post(
    `https://chatbotsplace.com/api/public/tts/standard`,
    {
      voiceId: 'aws-en-US-Joanna',
      message: 'Hello, how can I help you today?'
    },
    {
      responseType: 'arraybuffer',
      headers: {
        authorization: `Bearer ${apiKey}`
      }
    }
  );
  fs.writeFileSync(`./hello.mp3`, data, 'binary');
}
Example Python
import requests
import json

apiKey = '<your-api-key>'  # Define your apiKey

headers = {
    'content-type': 'application/json',
    'authorization': f'Bearer {apiKey}'
}

payload = {
    'voiceId': 'aws-en-US-Joanna',
    'message': 'Hello, how can I help you today?'
}

url = 'https://chatbotsplace.com/api/public/tts/standard'

response = requests.post(url, headers=headers, data=json.dumps(payload))

with open('hello.mp3', 'wb') as f:
    f.write(response.content)

POST /api/public/tts/neural (Text-to-speech with natural voice)

Convert text into synthesized speech using natural voice. Natural TTS voices produce more human-like sounding speech at the expense of higher price. It is also supported in more languages and have more voices available.

The cost for this API is 0.1 💎 for 100 characters (rounded up to the next 100 characters). 1 gem can produce up to 1000 characters. Currently, the maximum message length is 3000 characters. Please contact us if you need a higher limit.

Refers to the Natural TTS voices table table for a list of voices and languages available.

POST Body
name type data type description
message required string The message to synthesize into speech.
voiceId optional string The ID of the voice to use to synthesize this message (e.g., "aws-en-US-Joanna"). Either voiceId or the language must be specified.
language optional string The language code used to synthesize this message (e.g., "en-US"). Either voiceId or the language must be specified.
gender optional string The gender of the voice to use for this message. Only used if language is specified.
Responses
http code content-type response
200 audio/mp3 Synthesized audio stream
400 text/plain The request is invalid. Please make sure that the POST body is correct.
401 text/plain Invalid API key
403 text/plain Insufficient gems
Example cURL
 curl -X POST -H "Content-Type: application/json" --data @post.json https://chatbotsplace.com/api/public/tts/neural
Example Javascript
async function run() {
  const { data } = await axios.post(
    `https://chatbotsplace.com/api/public/tts/neural`,
    {
      voiceId: 'aws-en-US-Joanna',
      message: 'Hello, how can I help you today?'
    },
    {
      responseType: 'arraybuffer',
      headers: {
        authorization: `Bearer ${apiKey}`
      }
    }
  );
  fs.writeFileSync(`./hello.mp3`, data, 'binary');
}
Example Python
import requests
import json

apiKey = '<your-api-key>'  # Define your apiKey

headers = {
    'content-type': 'application/json',
    'authorization': f'Bearer {apiKey}'
}

payload = {
    'voiceId': 'aws-en-US-Joanna',
    'message': 'Hello, how can I help you today?'
}

url = 'https://chatbotsplace.com/api/public/tts/neural'

response = requests.post(url, headers=headers, data=json.dumps(payload))

with open('hello.mp3', 'wb') as f:
    f.write(response.content)

POST /api/public/speech-recognition (Speech-to-text transcription)

Transcribe an audio file into text. Audio file must be 25MB or less. Audio file can be one of these formats: mp3, mp4, mpeg, mpga, m4a, wav, or webm.

The cost for this API is 0.05 💎 per 10 seconds (rounded up to the nearest 10 seconds). For example, a 5-second audio file will cost 0.05 💎. A 1-minute audio file will cost 0.3 💎.

Note that unlike the other ChatbotsPlace API, the content-type for this request must be multipart/form-data.

POST Body
name type data type description
file required string The audio file to transcribe.
language optional string The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency.
Responses
http code content-type response
200 application/json {"cost": number, "language": string, "duration": number, "text": string, "segments": array }
400 text/plain The request is invalid. Please make sure that the POST body is correct.
401 text/plain Invalid API key
403 text/plain Insufficient gems
Example cURL
 curl -X POST -H "Content-Type: multipart/form-data" --data @post.json https://chatbotsplace.com/api/public/speech-recognition
Example Javascript
async function run() {
  const { data } = await axios.post(
    `https://chatbotsplace.com/api/public/speech-recognition`,
    {
      file: fs.createReadStream('./hello.mp3')
    },
    {
      headers: {
        'content-type': 'multipart/form-data',
        authorization: `Bearer ${apiKey}`
      }
    }
  );
  console.log(data);
}
Example Python
import requests

apiKey = '<your-api-key>'  # Define your apiKey

headers = {
    'authorization': f'Bearer {apiKey}'
}

with open('./hello.mp3', 'rb') as f:
    files = {
        'file': f,
    }
    response = requests.post('https://chatbotsplace.com/api/public/speech-recognition', headers=headers, files=files)
    data = response.json()
    print(data)

Chatbot versions and pricings

Version Name AI Model Max input Max output Pricing (per conversation)
v3.5 ChatGPT v3.5 gpt-3.5-turbo-1106 3000 tokens 1000 tokens -0.1💎
v3.5_16K ChatGPT v3.5 (16K) gpt-3.5-turbo-1106 16000 tokens 4000 tokens -1💎
v4.0 ChatGPT v4.0 gpt-4-1106-preview 16000 tokens 4000 tokens -15💎
claudeinstant Anthropic Claude Instant anthropic.claude-instant-v1 16000 tokens 4000 tokens -1💎
claude_v2 Anthropic Claude V2 anthropic.claude-v2 16000 tokens 4000 tokens -15💎
jurassic_2_ultra AI21 Labs Jurassic-2 Ultra ai21.j2-ultra-v1 8000 tokens 4000 tokens -15💎
bard_v1 Google Bard chat-bison-001 8000 tokens 1000 tokens -0.1💎