Betahunter API

Introduction

Send the thread you have so far for a lead. Betahunter decides whether it is the creator's turn, generates a reply in her voice, and returns the message (or burst of messages) to send back.

Authentication

Every request authenticates with your secret API key, sent as a Bearer token in the Authorization header:

Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx

Keys start with bh_live_. You can also send the key in an X-API-Key header instead. Keep it server-side, anyone who has it can spend your credits. A missing, unknown, or disabled key returns 401.

No key yet? Get one on Telegram.

Quickstart

One call generates the next reply for a lead who just messaged you:

curl https://api.betahunter.app/v1/generateResponse \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "accountId": "acct_42",
    "recipient": { "id": "u_88", "name": "Bob" },
    "chatHistory": [
      { "role": "user", "content": "hey", "timestamp": 1730000000 }
    ],
    "persona": { "name": "Ava", "ctaLink": "https://onlyfans.com/ava" }
  }'

How billing works

You are billed in conversations, not messages or tokens.

• A conversation is one lead in one of your accounts, identified by accountId + recipient.id. The API returns its conversationId.
• You are charged one credit the first time the engine produces a reply in a conversation. Every later reply in that same conversation is free, even after your balance reaches zero.
• Turns that generate nothing (not your turn, capped, out of credits, or blocked) are never charged.
• Check your remaining credits any time with GET /v1/balance.

Generate a reply

Send the recent thread you have so far. The engine appends only the genuinely new messages, decides whether to respond, and returns the reply to send.

The engine replies only when it is the creator's turn, that is, when the last message in chatHistory is from the lead ("role": "user"). If the thread is empty or the last message is the creator's, you get notOurTurn: true and nothing to send.

Request body

Recipient object

Message object (each chatHistory item)

Persona object

Photo object (each persona.photos item)

Response

The endpoint always returns 200. The body tells you what to do through content plus a set of outcome flags. When any flag is true, content is empty and you were not charged.

Content item

Example

{
  "accountId": "acct_42",
  "recipient": { "id": "u_88", "name": "Bob" },
  "chatHistory": [
    { "role": "assistant", "content": "heyy what are you up to", "timestamp": 1730000000 },
    { "role": "user", "content": "just relaxing, you?", "timestamp": 1730000120 }
  ],
  "persona": { "name": "Ava", "ctaLink": "https://onlyfans.com/ava" }
}

{
  "content": [
    { "type": "text", "content": "mmm relaxing sounds nice" },
    { "type": "text", "content": "i could think of a few better ways to relax tho 😉" }
  ],
  "converted": false,
  "notOurTurn": false,
  "timewaste": false,
  "aiCreditOver": false,
  "underage": false,
  "conversationId": "k3p9x2:acct_42:u_88"
}

Send each content item as its own message, in order, with natural delays. That multi-message burst is the human cadence the engine is built around.

Check balance

Returns the remaining conversation credits for your key.

curl https://api.betahunter.app/v1/balance \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx"

{ "creditsRemaining": 920 }

Errors

Authentication, validation, and capacity problems use standard HTTP status codes. Business outcomes (not your turn, capped, out of credits, blocked) are not errors, they come back as 200 with a flag set, as described above.

Error bodies are JSON: { "error": "unauthorized", "message": "..." }. Validation errors (422) also include a details array of { field, message } entries.

Rate limits

• 6,000 requests per minute, per key.
• 3,000 media-bearing requests per minute, per key.

Exceeding either limit returns 429. Need higher limits? Ask on Telegram.