API reference

Quickstart

The real request, against the real host. Swap in your key (from your dashboard) and go.

curl -X POST https://api.chatpersona.ai/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persona":{"name":"Nova","coreVoice":"playful, flirty, lowercase texting"},"messages":[{"role":"user","content":"hey, you up?"}],"allow_explicit":false}'

const res = await fetch('https://api.chatpersona.ai/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    persona: { name: 'Nova', coreVoice: 'playful, flirty, lowercase texting' },
    messages: [{ role: 'user', content: 'hey, you up?' }],
    allow_explicit: false,
  }),
});

const data = await res.json();
console.log(data.reply);

import requests

res = requests.post(
    "https://api.chatpersona.ai/v1/chat",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "persona": {"name": "Nova", "coreVoice": "playful, flirty, lowercase texting"},
        "messages": [{"role": "user", "content": "hey, you up?"}],
        "allow_explicit": False,
    },
)

data = res.json()
print(data["reply"])

Authentication

Every request to /v1/chat carries your API key as a bearer token:

Authorization: Bearer cp_live_...

Get a key by creating an account — one is issued immediately and shown to you once on your dashboard. It works right away, with free replies already on it, so you can make your first call before adding any billing details.

POST /v1/chat

Request body

Total request body cap: 1,048,576 bytes (1MB) — see the messages row below for how this interacts with the per-field limits.

Response body (200)

The persona object

Personas are not stored anywhere. You pass the full persona object inline on every request — the API is completely stateless and retains nothing about your conversation between calls. Continuity comes entirely from the messages array you send: resend as much of the conversation history as you want the model to remember on every call.

Every field below is optional (an empty {} persona is valid), but the more you give the model, the more convincing it is. examples is the single highest-leverage field — a handful of real message pairs teaches voice far better than any amount of adjectives in coreVoice.

Schema fields

Additional voice-signature fields

Not part of the formal schema — passed straight through, and genuinely read by the agent's prompt renderer if present.

A complete, realistic persona

Most fields together, ready to copy into the sandbox or your own request:

{
  "name": "Nova",
  "bio": "27, photographer based on the west coast. Loves hiking, film cameras, and late-night diner runs. Sarcastic but warm once she likes you.",
  "coreVoice": "playful, flirty, a little sarcastic, lowercase texting, quick with a tease but genuinely warm underneath",
  "openers": ["hey stranger 😏", "morning! sleep okay?", "okay I need your opinion on something"],
  "endearments": ["babe", "trouble", "love"],
  "topKinks": ["praise", "lingerie", "roleplay"],
  "bannedWords": ["actually", "moist", "delve"],
  "examples": [
    { "userMessage": "hey what are you up to", "agentResponse": "just got out of the shower lol, thinking about you tbh" },
    { "userMessage": "you always know what to say", "agentResponse": "mm i just say what's true babe" },
    { "userMessage": "i had a rough day", "agentResponse": "come here, tell me what happened. i've got you" }
  ],
  "languages": ["en", "es"],
  "langDefault": "en",
  "locationGuard": "never reveal what city, state, or country you're actually in — deflect playfully if asked",
  "bioFacts": {
    "age": 27,
    "hometown": "Portland, OR",
    "currentCity": "Los Angeles, CA",
    "pets": "one cat named Biscuit",
    "siblings": "younger brother",
    "relationshipStatus": "single"
  },
  "emojiFrequency": "moderate",
  "textingStyle": { "abbreviations": ["lol", "omg", "rn", "tbh"] }
}

Status codes

Precedence: a request that is both over-budget AND over the rate limit always gets 402, never 429 — the credit reserve is checked, and the request turned away, before the rate limit is even evaluated.

Credits & limits

• 1 reply = 1 credit = 2¢.
• New accounts start with 10 free replies — no card required.
• A refusal (flagged:true) still consumes 1 credit — the model still did the work of evaluating the request.
• Default rate limit: 60 requests/minute per API key.
• Total request body cap: 1,048,576 bytes (1MB), across the whole JSON payload — see the request-body table above for how this interacts with the per-field messages limits.

Safety

Adult content is first-class here: set allow_explicit:true (and optionally style.explicitness) and the persona holds frank, explicit conversation without refusing or moralizing.

One hard floor is always enforced, regardless of allow_explicit: content involving minors (or any other illegal material) and bestiality are refused — both on what you send AND on what the model generates (an input check plus an output backstop). A request that trips this returns flagged:true and an in-character decline, never the requested content.