Talk to a character (one turn)
Called from the EMBED’S BROWSER with the session token (the token IS the auth, no API key). The persona / lore / stance palette are loaded SERVER-side from the stored character; the client only sends what it said. Returns the character’s reply, the stance it moved to, an emotion, the updated affect, and an optional action. Metered as a ‘say’ turn.
curl --request POST \
--url https://api.alakazam.gg/v1/characters/{id}/say \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text": "<string>",
"token": "<string>",
"currentStance": "<string>",
"history": [
{
"role": "<string>",
"text": "<string>"
}
],
"affect": {},
"memory": "<string>"
}
'import requests
url = "https://api.alakazam.gg/v1/characters/{id}/say"
payload = {
"text": "<string>",
"token": "<string>",
"currentStance": "<string>",
"history": [
{
"role": "<string>",
"text": "<string>"
}
],
"affect": {},
"memory": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
text: '<string>',
token: '<string>',
currentStance: '<string>',
history: [{role: '<string>', text: '<string>'}],
affect: {},
memory: '<string>'
})
};
fetch('https://api.alakazam.gg/v1/characters/{id}/say', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.alakazam.gg/v1/characters/{id}/say",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'text' => '<string>',
'token' => '<string>',
'currentStance' => '<string>',
'history' => [
[
'role' => '<string>',
'text' => '<string>'
]
],
'affect' => [
],
'memory' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.alakazam.gg/v1/characters/{id}/say"
payload := strings.NewReader("{\n \"text\": \"<string>\",\n \"token\": \"<string>\",\n \"currentStance\": \"<string>\",\n \"history\": [\n {\n \"role\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"affect\": {},\n \"memory\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.alakazam.gg/v1/characters/{id}/say")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"text\": \"<string>\",\n \"token\": \"<string>\",\n \"currentStance\": \"<string>\",\n \"history\": [\n {\n \"role\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"affect\": {},\n \"memory\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.alakazam.gg/v1/characters/{id}/say")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text\": \"<string>\",\n \"token\": \"<string>\",\n \"currentStance\": \"<string>\",\n \"history\": [\n {\n \"role\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"affect\": {},\n \"memory\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"reply": "<string>",
"stance": "<string>",
"emotion": "<string>",
"affect": {},
"action": {},
"mock": true
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}Authorizations
The scoped runtime session JWT from POST /v1/sessions/token. The embed's browser presents it (Authorization: Bearer, or a token body field) to the runtime exchange routes. Not an API key.
Path Parameters
Body
Response
The character's turn
One character turn.
What the character says aloud.
The stance id it moved to.
Running mood + rapport {v,a,d,rapport}.
An optional thing it DOES this turn (show_image | fetch_object | change_location).
Present and true only for a TEST-mode session token, a canned reply, no LLM call. See Testing.
curl --request POST \
--url https://api.alakazam.gg/v1/characters/{id}/say \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text": "<string>",
"token": "<string>",
"currentStance": "<string>",
"history": [
{
"role": "<string>",
"text": "<string>"
}
],
"affect": {},
"memory": "<string>"
}
'import requests
url = "https://api.alakazam.gg/v1/characters/{id}/say"
payload = {
"text": "<string>",
"token": "<string>",
"currentStance": "<string>",
"history": [
{
"role": "<string>",
"text": "<string>"
}
],
"affect": {},
"memory": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
text: '<string>',
token: '<string>',
currentStance: '<string>',
history: [{role: '<string>', text: '<string>'}],
affect: {},
memory: '<string>'
})
};
fetch('https://api.alakazam.gg/v1/characters/{id}/say', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.alakazam.gg/v1/characters/{id}/say",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'text' => '<string>',
'token' => '<string>',
'currentStance' => '<string>',
'history' => [
[
'role' => '<string>',
'text' => '<string>'
]
],
'affect' => [
],
'memory' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.alakazam.gg/v1/characters/{id}/say"
payload := strings.NewReader("{\n \"text\": \"<string>\",\n \"token\": \"<string>\",\n \"currentStance\": \"<string>\",\n \"history\": [\n {\n \"role\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"affect\": {},\n \"memory\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.alakazam.gg/v1/characters/{id}/say")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"text\": \"<string>\",\n \"token\": \"<string>\",\n \"currentStance\": \"<string>\",\n \"history\": [\n {\n \"role\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"affect\": {},\n \"memory\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.alakazam.gg/v1/characters/{id}/say")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text\": \"<string>\",\n \"token\": \"<string>\",\n \"currentStance\": \"<string>\",\n \"history\": [\n {\n \"role\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"affect\": {},\n \"memory\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"reply": "<string>",
"stance": "<string>",
"emotion": "<string>",
"affect": {},
"action": {},
"mock": true
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}{
"detail": "<string>",
"errors": [
"<string>"
],
"schemaVersion": "<string>"
}
