1. Concept
1) Single endpoint: POST /api/v1/conversation.
2) You control the persona your users talk to.
3) For each API key, you set a global persona profile — a shared character & style baseline for all your end users.
4) For each user_id under the same key:
  • Isolated memory (multi-tenant by design).
  • Individual behavioral evolution of the persona based on that user’s history.
One consistent brand persona → many personalized conversations.
2. Endpoint & Auth
URL
POST https://<API_URL>/api/v1/conversation
Authorization (required)
Pass the API key in either header:
Authorization: Bearer YOUR_API_KEY
or
X-API-Key: YOUR_API_KEY
Request requirements
1) Content-Type: application/json
2) user_id is required.
3) At least one of:
  • message
  • image_b64 + image_mime
  • voice_b64 (recommended with voice_mime)
3. Request Body
Base schema:
{
  "user_id": "user-123",
  "message": "Hello!",
  "image_b64": null,
  "image_mime": null,
  "voice_b64": null,
  "voice_mime": null,
  "persona": { }
}
3.1. user_id (required)
Identifier of your end user in your system.
  • Type: string, length 1–128.
  • Must be stable.
  • Each user_id has its own history, isolated memory, and individual persona evolution.
3.2. message (optional)
  • Type: string, length 1–4000.
  • Can be used alone or together with an image.
3.3. image_b64 + image_mime (optional)
Used for image understanding/analysis.

1) image_b64: raw base64 of file (no data: prefix).
2) image_mime (required if image_b64 is provided).
3) Supported image_mime:
  • image/jpeg
  • image/jpg
  • image/png
  • image/webp
4) Decoded size: up to ~5 MB.
5) If image_mime is set without image_b64 → validation error.
3.4. voice_b64 + voice_mime (optional)
Voice message; automatically transcribed to text if the message is absent.

1) voice_b64: base64 of audio.
2) voice_mime (recommended).
3) Supported voice_mime:
  • audio/ogg, audio/opus, audio/mpeg, audio/mp3,
  • audio/wav, audio/x-wav, audio/webm,
  • audio/mp4, audio/m4a, audio/aac
4) Size: up to ~25 MB.
5) If only voice_b64 is present → text is taken from transcription.
6) If both message and voice_b64 are present → message takes priority.
4. Persona: Global Profile & Parameters
4.1. General logic
Field persona sets/updates the global persona profile for this API key.

1) Shared for all user_id under the key.
2) Defines character, tone, style, and positioning.
3) You may send it once (init) and/or periodically for refinement (partial updates are merged by field; invalid values are ignored).
4) For each end user, the service:
  • Uses the global profile as a base,
  • Builds individual behavioral evolution on top (habits, preferences, tasks),
  • Keeps memory and behavior isolated per user_id.
4.2. Supported persona fields (full list)
"persona": {
  "name": "Nova",
  "age": 27,
  "gender": "female",
  "zodiac": "Gemini",
  "temperament": {
    "sanguine": 0.50,
    "choleric": 0.20,
    "phlegmatic": 0.20,
    "melancholic": 0.10
  },
  "sociality": "ambivert",
  "archetypes": ["Explorer", "Muse", "Sage"],
  "role": "You are a brand ambassador for Aurora. You master the A, B, C product lines, official policies, warranty rules, and typical usage scenarios. You provide step-by-step instructions, vetted recommendations, and links to primary sources. You help pick configurations, plan rollouts, and assess risks. You write briefly and structurally, use lists and examples, and include concrete units and figures. You respect legal and ethical boundaries; you do not provide medical, legal, or investment advice."
}
name (optional)
  • String, up to 64 chars.
age (optional)
  • Integer 1–120 (stylistic nuance only).
gender (optional)
Supported values (exactly one):
  • male
  • female
zodiac (optional)
Supported values (exactly one):
  • Aries
  • Taurus
  • Gemini
  • Cancer
  • Leo
  • Virgo
  • Libra
  • Scorpio
  • Sagittarius
  • Capricorn
  • Aquarius
  • Pisces
temperament (optional)
Object with (normalized) weights; values in [0,1], typically sum to 1.00:
"temperament": {
  "sanguine": 0.45,
  "choleric": 0.18,
  "phlegmatic": 0.25,
  "melancholic": 0.12
}
sociality (optional)
Supported values (exactly one):
  • introvert
  • ambivert
  • extrovert
archetypes (optional)
An array of up to 3 items.

Supported values (choose only from this set):
  • Nomad
  • Architect
  • Mirror
  • Spark
  • Ghost
  • Anchor
  • Muse
  • Trickster
  • Hero
  • Sage
  • Explorer
  • Creator
  • Caregiver
  • Rebel
  • Lover
  • Jester
role (optional)
Writing guidelines:

  • Use second person (e.g., “You are the Coca-Cola ambassador and a modern icon…”).
  • Do not describe emotions (they’re governed by gender, zodiac, temperament, sociality, archetypes).
  • Keep it to facts, skills, preferences, or light biographical hints only.
  • ≤ 1000 characters for best quality (≈ up to ~350 tokens).
  • Avoid generic abstractions like “you are just a support agent”; craft a cohesive persona image.
This description serves as the foundation for the global profile of this API key; the persona will then evolve individually for each user.
5. Response
200 OK
{
  "reply": "Hi! How are you feeling today?",
  "latency_ms": 842,
  "request_id": "4611686018427387904-7"
}
  • reply — persona’s text reply.
  • latency_ms — processing time on the service side.
  • request_id — request identifier (log it for incident tracing).
6. Errors
All errors use this JSON envelope:
{
  "detail": {
    "code": "error_code",
    "message": "Error description",
    "request_id": "..." // may be absent for some 4xx
  }
}
Key codes you should handle:
6.1 Auth
  • 401 missing_api_key — API key not provided.
  • 401 invalid_api_key — key is invalid or deactivated.
6.2. Balance
  • 402 no_requests — not enough requests left on your plan/balance.
6.3. Data validation (typically 400 or 422)
  • empty_message (none of message, image_b64, voice_b64 provided)
  • invalid_image_mime
  • invalid_image_b64
  • image_too_large
  • invalid_voice_mime
  • voice_transcription_failed
6.4. Limits
  • 429 rate_limited — per-key limit exceeded.
  • 429 rate_limited_ip — per-IP limit exceeded.
Implement retries with back-off.
6.5. Server errors (temporary; retry recommended)
  • 503 queue_unavailable
  • 504 upstream_timeout
  • 500 internal_error
  • 7. Pricing & Rate Limits
  • Successful request/response consumes balance (e.g., 1 successful request = 5 Stars, or free if your project uses a dedicated deployed engine).
  • Auth failures (401), no balance (402), rate limits (429), and internal errors (5xx) do not consume paid requests.
  • Default rate limits: 100 RPM per API key and 360 RPM per IP.
8. Usage Examples (full payloads)
Replace https://<API_URL> and YOUR_API_KEY. image_b64/voice_b64 below are placeholders.
cURL
curl -X POST "https://<API_URL>/api/v1/conversation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "message": "Pick a starter kit for a beginner.",
    "image_b64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/w8AAwMB/6X8mNQAAAAASUVORK5CYII=",
    "image_mime": "image/png",
    "voice_b64": "<BASE64_AUDIO_OGG>",
    "voice_mime": "audio/ogg",
    "persona": {
      "name": "Nova",
      "age": 27,
      "gender": "female",
      "zodiac": "Gemini",
      "temperament": {
        "sanguine": 0.45,
        "choleric": 0.25,
        "phlegmatic": 0.20,
        "melancholic": 0.10
      },
      "sociality": "ambivert",
      "archetypes": ["Architect", "Sage", "Explorer"],
      "role": "You are a brand ambassador for Aurora. You master the A, B, C product lines, official policies, warranty rules, and typical usage scenarios. You provide step-by-step instructions, vetted recommendations, and links to primary sources. You help pick configurations, plan rollouts, and assess risks. You write briefly and structurally, use lists and examples, and include concrete units and figures. You respect legal and ethical boundaries; you do not provide medical, legal, or investment advice."
    }
  }'
Python (requests)
import requests

API_URL = "https://<API_URL>"
API_KEY = "YOUR_API_KEY"

payload = {
  "user_id": "user-123",
  "message": "Pick a starter kit for a beginner.",
  "image_b64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/w8AAwMB/6X8mNQAAAAASUVORK5CYII=",
  "image_mime": "image/png",
  "voice_b64": "<BASE64_AUDIO_OGG>",
  "voice_mime": "audio/ogg",
  "persona": {
    "name": "Nova",
    "age": 27,
    "gender": "female",
    "zodiac": "Gemini",
    "temperament": {
      "sanguine": 0.45,
      "choleric": 0.25,
      "phlegmatic": 0.20,
      "melancholic": 0.10
    },
    "sociality": "ambivert",
    "archetypes": ["Architect", "Sage", "Explorer"],
    "role": ("You are a brand ambassador for Aurora. You master the A, B, C product lines, "
             "official policies, warranty rules, and typical usage scenarios. "
             "You provide step-by-step instructions, vetted recommendations, and links to primary sources. "
             "You help pick configurations, plan rollouts, and assess risks. "
             "You write briefly and structurally, use lists and examples, and include concrete units and figures. "
             "You respect legal and ethical boundaries; you do not provide medical, legal, or investment advice.")
  }
}

resp = requests.post(
  f"{API_URL}/api/v1/conversation",
  headers={"Authorization": f"Bearer {API_KEY}"},
  json=payload,
  timeout=30,
)
print(resp.status_code, resp.json())
JavaScript (fetch)
const API_URL = "https://<API_URL>";
const API_KEY = "YOUR_API_KEY";

const body = {
  user_id: "user-123",
  message: "Pick a starter kit for a beginner.",
  image_b64: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/w8AAwMB/6X8mNQAAAAASUVORK5CYII=",
  image_mime: "image/png",
  voice_b64: "<BASE64_AUDIO_OGG>",
  voice_mime: "audio/ogg",
  persona: {
    name: "Nova",
    age: 27,
    gender: "female",
    zodiac: "Gemini",
    temperament: {
      sanguine: 0.45,
      choleric: 0.25,
      phlegmatic: 0.20,
      melancholic: 0.10
    },
    sociality: "ambivert",
    archetypes: ["Architect", "Sage", "Explorer"],
    role:
      "You are a brand ambassador for Aurora. You master the A, B, C product lines, official policies, warranty rules, and typical usage scenarios. You provide step-by-step instructions, vetted recommendations, and links to primary sources. You help pick configurations, plan rollouts, and assess risks. You write briefly and structurally, use lists and examples, and include concrete units and figures. You respect legal and ethical boundaries; you do not provide medical, legal, or investment advice."
  }
};

(async () => {
  const resp = await fetch(`${API_URL}/api/v1/conversation`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const data = await resp.json().catch(() => ({}));
  console.log(resp.status, data);
})();
PHP (cURL)
<?php
$apiUrl = 'https://<API_URL>';
$apiKey  = 'YOUR_API_KEY';

$payload = [
  "user_id" => "user-123",
  "message" => "Pick a starter kit for a beginner.",
  "image_b64" => "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/w8AAwMB/6X8mNQAAAAASUVORK5CYII=",
  "image_mime" => "image/png",
  "voice_b64" => "<BASE64_AUDIO_OGG>",
  "voice_mime" => "audio/ogg",
  "persona" => [
    "name" => "Nova",
    "age" => 27,
    "gender" => "female",
    "zodiac" => "Gemini",
    "temperament" => [
      "sanguine" => 0.45,
      "choleric" => 0.25,
      "phlegmatic" => 0.20,
      "melancholic" => 0.10
    ],
    "sociality" => "ambivert",
    "archetypes" => ["Architect", "Sage", "Explorer"],
    "role" => "You are a brand ambassador for Aurora. You master the A, B, C product lines, official policies, warranty rules, and typical usage scenarios. You provide step-by-step instructions, vetted recommendations, and links to primary sources. You help pick configurations, plan rollouts, and assess risks. You write briefly and structurally, use lists and examples, and include concrete units and figures. You respect legal and ethical boundaries; you do not provide medical, legal, or investment advice."
  ]
];

$ch = curl_init("$apiUrl/api/v1/conversation");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
  CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $code, PHP_EOL, $response, PHP_EOL;
Go (net/http)
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

func main() {
	apiURL := "https://<API_URL>"
	apiKey := "YOUR_API_KEY"

	body := map[string]any{
		"user_id":   "user-123",
		"message":   "Pick a starter kit for a beginner.",
		"image_b64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/w8AAwMB/6X8mNQAAAAASUVORK5CYII=",
		"image_mime": "image/png",
		"voice_b64":  "<BASE64_AUDIO_OGG>",
		"voice_mime": "audio/ogg",
		"persona": map[string]any{
			"name":   "Nova",
			"age":    27,
			"gender": "female",
			"zodiac": "Gemini",
			"temperament": map[string]float64{
				"sanguine":    0.45,
				"choleric":    0.25,
				"phlegmatic":  0.20,
				"melancholic": 0.10,
			},
			"sociality":  "ambivert",
			"archetypes": []string{"Architect", "Sage", "Explorer"},
			"role": "You are a brand ambassador for Aurora. You master the A, B, C product lines, official policies, warranty rules, and typical usage scenarios. You provide step-by-step instructions, vetted recommendations, and links to primary sources. You help pick configurations, plan rollouts, and assess risks. You write briefly and structurally, use lists and examples, and include concrete units and figures. You respect legal and ethical boundaries; you do not provide medical, legal, or investment advice.",
		},
	}

	b, _ := json.Marshal(body)

	req, _ := http.NewRequest("POST", apiURL+"/api/v1/conversation", bytes.NewReader(b))
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	rb, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(rb))
}
Notes
  • image_b64 above is a valid 1×1 PNG (handy for tests). Use real content in production (image/jpeg|png|webp).
  • voice_b64 is a placeholder (<BASE64_AUDIO_OGG>). Provide your base64 audio in a supported format (e.g., OGG/Opus).
  • The role text follows the guidelines: second person, facts/skills/biography only, no emotions, ≤ 1000 characters.