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 as an optional JSON body field named licensekey on POST endpoints for drop-in compatibility. The Authorization header wins when both are present, and GET /v1/balance requires the header. 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 returns a successful non-empty bot turn in a conversation. Every later reply in that same conversation is free, even after your balance reaches zero.
• If you enable a lead filter and a conversation is skipped by it (tierFiltered or genderFiltered), you are charged 0.2 credit once for that conversation, far less than a full reply and never more than once.
• Turns that generate nothing (not your turn, capped, out of credits, blocked, or abandoned) are never charged.
• Because of the 0.2 filter charge, creditsRemaining can be fractional (e.g. 919.8).
• 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, unless you set generateOpener: true on an empty thread, in which case it writes the first message (the opener) instead.

Request body

Recipient object

Message object (each chatHistory item)

Persona object

Photo object (each persona.photos item)

Lead filters (optional)

Skip leads you do not want to engage, before any reply is generated. Set persona.tierFilter (country tier) and/or persona.filterFemales (gender). A skipped lead comes back with tierFiltered / genderFiltered set and no content, and is billed the 0.2 filter charge once (see How billing works).

For drop-in Capital compatibility the API also accepts these at the top level of the request: filterMaleOnly (boolean, maps to filterFemales), filterTiers (the country tiers to keep, 1 = highest income … 3 = lowest; e.g. [1, 2] keeps tiers 1–2 and skips tier 3, equivalent to tierFilter: "T3"), and nameForFilter (a name for the classifier when recipient.name is absent). Explicit persona values win over these aliases.

Response

Successful generate calls return 200. The body tells you what to do through content plus outcome fields. When notOurTurn, timewaste, aiCreditOver, orunderage is true, content is empty and you were not charged. tierFiltered and genderFiltered also return empty content, but a filtered conversation is billed 0.2 credit once. The compatibility key converted reports a chat-confirmed subscription inferred from lead text or an operator update; it is not payment confirmation.

Content item

Example

{
  "accountId": "acct_42",
  "presetId": "pre_7f2a9c",
  "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", "mediaPool": null },
    { "type": "text", "content": "i could think of a few better ways to relax tho 😉", "mediaPool": null }
  ],
  "converted": false,
  "notOurTurn": false,
  "timewaste": false,
  "aiCreditOver": false,
  "underage": false,
  "conversationId": "cust_123: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.

Dashboard presets

Use presets when you do not want to rebuild creator setup in your own product. A preset stores persona info, CTA rotation, follow-up messages, duplicate-lead controls, phases, and the media vault. Then your integration only passes presetId on POST /v1/generateResponse.

Create an inactive draft, populate both Main and Sexy categories, then activate it before calling generation with its presetId.

curl https://api.betahunter.app/v1/presets \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "name": "Ava main funnel",
    "persona": {
      "name": "Ava",
      "age": 22,
      "city": "Miami",
      "userInfo": "playful gym girl",
      "ctaInfo": "VIP page with daily drops",
      "ctaMinExchanges": 8
    },
    "ctas": [
      { "platform": "OnlyFans", "cta": "https://onlyfans.com/ava" }
    ],
    "leadControls": {
      "skipRecentlyMessagedLeads": true,
      "duplicateLeadCooldownDays": 30,
      "internalUsernames": ["ava_backup"]
    },
    "followUps": {
      "enabled": true,
      "maxFollowUps": 2,
      "messages": [
        { "message": "still thinking about you", "delayHours": 24 }
      ]
    }
  }'

Upload images as JSON base64, with type (Primary = Main or Sexy) and optional priority. Active presets require 1–5 images per category (2–10 total); new presets default to inactive drafts and may be incomplete. Create accepts bulk photos: each entry requires a unique, nonblank id and url, with type (Primary or Sexy) and optional integer priority. For example: {"id":"main-1","url":"https://your-cdn.example/main.jpg","type":"Primary"}. IDs are required for bulk create, not for URL/upload endpoints. Update does not replace photos. Photo endpoints return the full preset and enforce limits and duplicate rejection. Images never repeat in a conversation, including selected objection and follow-up attachments. Objection uploads share the same library. Existing oversized libraries require explicit curation; nothing is automatically removed.

Alternatively, use hosted URLs as below. Replace the preset ID with the Create response’s id and the example URLs with your own. Both requests must succeed before activation.

# Replace pre_7f2a9c with the id returned by Create, and use your hosted image URLs.
for type in Primary Sexy; do
  curl https://api.betahunter.app/v1/presets/pre_7f2a9c/photos \
    -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx" \
    -H "content-type: application/json" \
    -d "{\"url\":\"https://your-cdn.example/$type.jpg\",\"type\":\"$type\"}"
done

curl -X PUT https://api.betahunter.app/v1/presets/pre_7f2a9c \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{ "active": true }'

Voice notes

Production: the operator enables VOICE_LIVE_ENABLED=true on the backend and reloads it. Personas default on, including existing preview-era presets; no per-persona activation is needed. To opt out, uncheck “Enable voice notes for real leads” and save the persona (voiceSettings.enabled=false). Newly saved opt-outs persist. The server gate still defaults off and cannot be bypassed. The sender must support native type:"voice" delivery. Saved Objections overrides have separate controls.

Playground: “Test voice notes” affects only that session, independently of the live switches. Testing, uploading or selecting a recording does not enable voice for real leads.

The engine normally voices one early reply and one pitch; unused library recordings may answer naturally at other moments. Each voice reply is one recording. Limits are five general generations plus one reserved for the pitch, and ten total voice sends per conversation. Generation requires the backend’s ElevenLabs key and uses real provider credits. Explicit requests such as “in voice note” also work after the pitch. “Again” after audio, or “send the voice note again”, can replay the last confirmed recording without another generation; each replay uses a send slot and does not resend the link/photos.

Evergreen pitch: set voiceSettings.pitchReplacementNoteId to a recording from this preset’s library, or upload/select one beside “Exact pitch text sent with the link” and save the persona. At the first actual pitch it sends that recording, then the bare CTA link: no generated introduction or duplicate pitch text. Other media stays separate. The clip is reserved from earlier replies and reused across conversations without another provider call, once automatically per conversation; explicit replays still use a send slot. Keep the pitch text as the fallback; an empty ID restores automatic behavior. Live voice remains gated.

New speech defaults to Eleven v4; the playground shows the actual server model and delivery-tag status. Delivery tags use the existing reply-model call, without a separate speech rewrite or extra model request. Saved recordings retain their original sound.

POST /v1/presets/{presetId}/voice-notes/upload accepts filename, contentType (audio/mpeg or audio/mp3 for MP3; audio/mp4 or video/mp4 for MP4), dataBase64, an exact transcript, and optional name/whenToUse. MP3 or MP4 with audio, up to 25 MB. Both are packaged as audio-only MP4 for playback and delivery.

POST /v1/presets/{presetId}/voice-notes/generate accepts text plus optional name/whenToUse and saves an ElevenLabs recording. Both endpoints return the full preset with voiceNotes. Metadata can be edited with PUT and entries removed with DELETE /v1/presets/{presetId}/voice-notes/{noteId}.

Use the existing delivery acknowledgement endpoints for mixed voice/text turns. Retries reuse stored audio; never generate again or resend confirmed items. AI-identity verification auto-voicing is not included in this version.

You can also attach an already-hosted URL with POST /v1/presets/{presetId}/photos. Deleting a photo or preset removes library records, not image files: uploaded image bytes are retained for shared copies and existing conversations. Remote URLs are left untouched.

Returns the callable model ids and your saved presets, useful for a Capital-style dropdown before sending modelId and presetId.

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

Returns dashboard metrics by period, account, or preset, including follow-ups, CTA phase, chat-confirmed subscriptions, conversation origins, duplicate skips, internal-account skips, and lead filters. Chat-confirmed subscription metrics come from lead text or operator updates. They do not represent payment data.

curl "https://api.betahunter.app/v1/dashboard/analytics?period=30days&presetId=pre_7f2a9c" \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx"

Returns recent conversation summaries for the dashboard activity table and for operators who want to inspect why a lead was skipped or marked as a chat-confirmed subscription.

curl "https://api.betahunter.app/v1/dashboard/conversations?period=30days&limit=50" \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx"

Preset lead controls return messagedAlready or internalAccount on generateResponse when a lead should not be messaged. Those are normal 200 outcomes with empty content, so your sender can skip cleanly.

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 }

Funnel statistics

Returns a funnel rollup for the authenticated key. Omit the body for all-time, all-account stats, or pass an account and period to narrow the result. Headline rates use engine-authored opener conversations. Subscription outcomes are inferred from chat text or operator updates and do not confirm payment.

curl https://api.betahunter.app/v1/statistics \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{ "period": "7days", "account": "acct_42" }'

{
  "conversations": 10,
  "messages": 134,
  "ctaShared": 6,
  "engineAuthoredOpenerConversations": 10,
  "chatConfirmedSubscriptions": 3,
  "chatConfirmedSubscriptionRate": 0.3,
  "postCtaChatConfirmedSubscriptions": 2,
  "postCtaChatConfirmedSubscriptionRate": 0.2,
  "originCounts": {
    "engineAuthoredOpeners": 10,
    "clientAuthoredOpeners": 2,
    "leadFirst": 1,
    "other": 0
  },
  "conversions": 3,
  "conversionRate": 0.3,
  "blocked": 1
}

Request body

Response

Errors

Authentication, validation, and capacity problems use standard HTTP status codes. Generate business-stop 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

• POST /v1/generateResponse: 6,000 requests per minute, per key.
• POST /v1/generateResponse: 3,000 media-bearing requests per minute, per key.

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