# Oh API — AI Integration Guide

Version: 1.0

Use this document as the complete implementation context for an Oh API integration. Start with the smallest outcome the user requested, use the recipes below, and consult the full endpoint reference that follows.

## Rules for AI coding tools

1. Keep `OH_API_KEY` in a server-only environment variable.
2. Call Oh API from server code or a narrow server-side proxy. Never expose the key in browser code, mobile bundles, logs, or local storage.
3. Use `https://api.oh.xyz` as the production base URL.
4. Send `X-API-Key` on every request and `Content-Type: application/json` for JSON bodies.
5. Reuse a room for a conversation so the character keeps context.
6. Treat text and audio replies as synchronous. Treat image and video generation as asynchronous.
7. For asynchronous jobs, poll with backoff, stop on `completed` or `failed`, and use the final `url` returned by the status endpoint.
8. Surface the upstream status code and error body to the developer without leaking credentials.

## Five-minute quick start

### 1. Add the server-only secret

```bash
OH_API_KEY=replace_with_your_api_key
```

### 2. Add a server-side client

This TypeScript helper works in a Next.js server module or a Node.js service:

```ts
import "server-only";

const OH_API_BASE_URL = "https://api.oh.xyz";

export async function callOhApi<T>(
  path: string,
  init: RequestInit = {},
): Promise<T> {
  const apiKey = process.env.OH_API_KEY;

  if (!apiKey) {
    throw new Error("OH_API_KEY is not configured");
  }

  const headers = new Headers(init.headers);
  headers.set("X-API-Key", apiKey);
  if (init.body && !headers.has("Content-Type")) {
    headers.set("Content-Type", "application/json");
  }

  const response = await fetch(`${OH_API_BASE_URL}${path}`, {
    ...init,
    headers,
    cache: "no-store",
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Oh API ${response.status}: ${body || response.statusText}`);
  }

  return response.json() as Promise<T>;
}
```

### 3. Create a room and send a message

```ts
const room = await callOhApi<{ room_id: string }>("/api/v1/rooms", {
  method: "POST",
  body: JSON.stringify({
    character_id: "12345",
    user_id: "user_789",
    user: { name: "Alex" },
  }),
});

const reply = await callOhApi<{ content: string }>("/api/v1/text", {
  method: "POST",
  body: JSON.stringify({
    room_id: room.room_id,
    prompt: "Hello! Tell me about yourself.",
  }),
});

console.log(reply.content);
```

## Outcome recipes

### Build character chat

1. Read saved characters from `GET /api/v1/customer-library`.
2. Create or reuse a room with `POST /api/v1/rooms`.
3. Send each turn to `POST /api/v1/text` with `{ room_id, prompt }`.

### Generate an image

1. Submit `POST /api/v1/images` with `{ character_id, prompt, resolution }`, or use `{ room_id }` for room-aware generation.
2. Store the returned `job_id`.
3. Poll `GET /api/v1/jobs/{job_id}/status` every 2–5 seconds.
4. Stop on `completed` or `failed`; display the completed response's `url`.

### Generate a video

1. Submit `POST /api/v1/videos/create` using `character_id`, `image_url`, or `room_id`.
2. For jobs returning `job_id`, poll `GET /api/v1/jobs/{job_id}/status`.
3. For compatibility flows returning `id`, poll `GET /api/v1/videos/get?videoId={id}`.
4. Stop polling after five minutes and surface failures.

### Create a character

1. Submit `POST /api/v2/characters/generate`.
2. Poll `GET /api/v2/characters/{characterGuid}/status` until `ready`.
3. Review with `GET /api/v2/characters/{characterGuid}`.
4. Save with `POST /api/v2/characters/save`.
5. Poll status until `saved`, then use the returned `characterId`.

### Generate spoken audio

Call `POST /api/v1/audio/notes` with `{ room_id, prompt }` or direct character context. The response is synchronous and includes the audio `url` and text `content`; do not poll a job endpoint.

## Canonical resources

- Interactive documentation: `https://api.oh.xyz/documentation`
- OpenAPI 3.0 JSON: `https://api.oh.xyz/openapi.json`
- Compact AI index: `https://api.oh.xyz/llms.txt`
- Complete AI context: `https://api.oh.xyz/llms-full.txt`

---

# Complete endpoint reference

# Core API Documentation

Version: 1.0

This document describes the public API for character management, digital twin creation, conversation rooms, text and audio replies, media generation, profile extraction, voices, and face similarity services.

The API is organized around REST endpoints under `/api/v1` and `/api/v2`. JSON is used for request and response bodies unless otherwise noted.

## Base URL

Production:

```text
https://api.oh.xyz
```

Staging and preview environments may expose separate base URLs.

## Authentication

Partner-facing endpoints require an API key.

```http
X-API-Key: <api_key>
Content-Type: application/json
```

Use HTTPS for all production requests. Keep API keys server-side and do not expose them in browser clients or mobile apps.

## Common Concepts

### IDs

The API uses several identifiers:

| Name | Description |
| --- | --- |
| `characterId` | Saved character identifier. |
| `characterGuid` | Generated character job/result identifier used by v2 character workflows. |
| `digitalTwinId` | Digital twin identifier. |
| `userId` | User identifier for rooms and user-scoped resources. |
| `room_id` | Conversation room identifier. |
| `message_id` | Message identifier. |
| `job_id` | Async generation job identifier. |

### Async Jobs

Image and video generation are asynchronous. Text and audio reply generation are synchronous.

For async workflows:

1. Submit the generation request.
2. Store the returned job or resource identifier.
3. Poll `GET /api/v1/jobs/{job_id}/status` until the job is complete or failed.
4. Use the returned `url` when complete.

Async job responses commonly include:

| Field | Description |
| --- | --- |
| `job_id` | Async job identifier. |
| `status` | `queued`, `processing`, `completed`, or `failed`. |
| `presigned_url` | Temporary upload/result URL returned when a job starts. |
| `url` | Generated media URL returned by the status endpoint when complete. |
| `results` | Job metadata such as enhanced prompt, detected content level, follow-up text, or generated content. |
| `error` | Error message when a job fails. |

Media result URLs may expire. Poll the status endpoint again to mint a fresh URL.

### Errors

The media/chat API returns `400` for request errors and `5xx` for service failures. The response body message distinguishes the cause.

Common `400` causes:

| Cause | Notes |
| --- | --- |
| Missing or invalid body | Required JSON fields are missing or malformed. |
| Missing or invalid auth headers | API key is missing or invalid. |
| Unknown or unowned resource | The requested room, message, or job does not belong to the calling client. |
| Moderation rejection | The prompt failed content moderation. |

Retry transient `5xx` errors with backoff.

## Characters V1

Characters V1 is deprecated. Use the Characters V2 endpoints for new integrations.

## Characters V2

The v2 character API supports async character generation with profile generation and a combined affiliate-style generate-and-save flow.

### Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v2/characters/generate` | Generate an AI character asynchronously. |
| `POST` | `/api/v2/characters/affiliate/generate-and-save` | Generate and save a character in a single async workflow. |
| `GET` | `/api/v2/characters/{characterGuid}` | Get a generated character. |
| `POST` | `/api/v2/characters/save` | Save a generated character asynchronously. |
| `GET` | `/api/v2/characters/{characterGuid}/status` | Get character save/generation status. |

### Generate Character V2 Request

Required fields: `nationality`, `ethnicity`, `firstName`, `lastName`, `gender`.

This request supports all v1 character-generation profile fields, plus richer creator profile metadata:

| Field group | Fields |
| --- | --- |
| Identity | `firstName`, `lastName`, `alias`, `dateOfBirth`, `gender`, `nationality`, `ethnicity`, `hideAge` |
| Profile | `biography`, `job`, `whereYouLive`, `backstory`, `textingStyle`, `contentLevel` |
| Personality | `interests`, `personality`, `conversationStyle`, `attitude`, `relationshipStyle`, `relationshipStatus`, `sexDrive` |
| Physical attributes | `height`, `weight`, `bodyBuild`, `bodyShape`, `bodyType`, `physicalCharacteristics`, `skinTone`, `hairLength`, `hairColour`, `hairColor`, `eyeColour`, `eyeColor`, `buttSize`, `breastSize`, `breastPertness`, `nippleColour`, `vaginaHair`, `vaginaSize`, `penisSize`, `tattoos` |
| Adult preferences | `orientation`, `sexualExperience`, `kinks`, `kinksStrings`, `extraDetails`, `sexPositions` |
| Prompts | `roleplayPrompts`, `flirtingPrompts`, `imageRequestPrompts`, `additionalDescription` |
| Reference image | `style` — `realistic` (default) or `artificial`: a deliberately AI-looking, hyper-polished, glossy character rather than a photorealistic one. Stored with the character (echoed as `character.style` by `GET /api/v2/characters/{characterGuid}`); every image job for the character follows it. Any other value returns 400. |
| Media | `profileImageUrl`, `coverVideoUrl`, `imageModel`, `voiceUrl`, `audioSpeed` |
| Social handles | `socialHandleInstagram`, `socialHandleTiktok`, `socialHandleTwitter`, `socialHandleYoutube`, `socialHandleTwitch`, `socialHandleTelegram` |

### Prompt Item

Prompt arrays use this shape:

```json
{
  "title": "Prompt title",
  "description": "Prompt description"
}
```

### Save Character V2 Request

Required field: `characterGuid`.

The save request accepts `characterGuid` plus the optional identity, profile, media, social, and prompt fields listed above.

## Character Attribute Values

Use these endpoints to retrieve allowed values for controlled character attributes.

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/v1/characters/nationalities` | Get allowed nationalities. |
| `GET` | `/api/v1/characters/ethnicities` | Get allowed ethnicities. |
| `GET` | `/api/v1/characters/hair-lengths` | Get allowed hair lengths. |
| `GET` | `/api/v1/characters/hair-colours` | Get allowed hair colours. |
| `GET` | `/api/v1/characters/eye-colours` | Get allowed eye colours. |
| `GET` | `/api/v1/characters/skin-tones` | Get allowed skin tones. |
| `GET` | `/api/v1/characters/breast-sizes` | Get allowed breast sizes. |
| `GET` | `/api/v1/characters/nipple-colours` | Get allowed nipple colours. |
| `GET` | `/api/v1/characters/breast-pertness` | Get allowed breast pertness options. |
| `GET` | `/api/v1/characters/vagina-hair` | Get allowed pubic hair styles. |
| `GET` | `/api/v1/characters/vagina-sizes` | Get allowed vagina sizes. |
| `GET` | `/api/v1/characters/body-builds` | Get allowed body builds. |
| `GET` | `/api/v1/characters/body-shapes` | Get allowed body shapes. |
| `GET` | `/api/v1/characters/butt-sizes` | Get allowed butt sizes. |
| `GET` | `/api/v1/characters/orientations` | Get allowed orientations. |
| `GET` | `/api/v1/characters/sexual-experiences` | Get allowed sexual experience values. |
| `GET` | `/api/v1/characters/kinks` | Get allowed kinks. |
| `GET` | `/api/v1/characters/sex-positions` | Get allowed sex positions. |
| `GET` | `/api/v1/characters/relationship-styles` | Get allowed relationship styles. |
| `GET` | `/api/v1/characters/ai-relationship-styles` | Get allowed AI relationship styles. |
| `GET` | `/api/v1/characters/personalities` | Get allowed personalities. |
| `GET` | `/api/v1/characters/sex-drives` | Get allowed sex drives. |
| `GET` | `/api/v1/characters/conversation-styles` | Get allowed conversation styles. |
| `GET` | `/api/v1/characters/attitudes` | Get allowed attitudes. |
| `GET` | `/api/v1/characters/relationship-statuses` | Get allowed relationship statuses. |
| `GET` | `/api/v1/characters/interests` | Get allowed interests. |
| `GET` | `/api/v1/characters/jobs` | Get job suggestions. |

### How to Use Taxonomies

For app builds, use the taxonomy endpoints above as the source of truth for selectable values. These lists may change over time without a full API version change.

Recommended implementation pattern:

1. Fetch taxonomy values when rendering character-creation forms.
2. Cache values client-side or server-side for a short period.
3. Submit the selected label/value exactly as returned by the taxonomy endpoint.
4. Use the schema values below as a build-time reference or fallback.

### Taxonomy Alias Endpoints

The API also exposes shorter `/api/v1/terms/...` endpoints for several common taxonomies.

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/v1/terms/eye_color` | Get eye color terms. |
| `GET` | `/api/v1/terms/body_type` | Get body type terms. |
| `GET` | `/api/v1/terms/gender` | Get gender terms. |
| `GET` | `/api/v1/terms/hair_color` | Get hair color terms. |
| `GET` | `/api/v1/terms/orientation` | Get orientation terms. |
| `GET` | `/api/v1/terms/ethnicity` | Get ethnicity terms. |
| `GET` | `/api/v1/terms/breast_size` | Get breast size terms. |
| `GET` | `/api/v1/terms/interests` | Get interests terms. |
| `GET` | `/api/v1/terms/kinks` | Get kinks terms. |
| `GET` | `/api/v1/terms/personality` | Get personality terms. |
| `GET` | `/api/v1/terms/traits` | Get traits terms. |

### Known Selectable Values

The following values are embedded in the OpenAPI schemas and can be used as a practical reference for UI dropdowns, validation, and test data.

| Field | Taxonomy endpoint | Known values |
| --- | --- | --- |
| `nationality` | `/api/v1/characters/nationalities` | American, Brazilian, Russian, Colombian, Ukrainian, Japanese, Filipino, Thai, Mexican, Canadian, British, Korean (South), Vietnamese, Indian, Chinese, German, French, Italian, Spanish, Australian, Swedish, Polish, Dutch, Venezuelan, Dominican, Argentine, Peruvian, Czech, Romanian, Hungarian, Turkish, Lebanese, Israeli, Greek, Serbian, Croatian, Bulgarian, Belgian, Norwegian, Danish, Finnish, Irish, Scottish, Portuguese, New Zealander, South African, Jamaican, Puerto Rican, Cuban, Costa Rican, Panamanian, Salvadoran, Nigerian, Ghanaian, Kenyan, Moroccan, Algerian, Egyptian, Tunisian, Pakistani, Bangladeshi, Indonesian, Malaysian, Singaporean, Taiwanese, Hong Konger, Emirati (UAE), Saudi, Qatari, Kuwaiti, Jordanian, Syrian, Iranian, Afghan, Kazakh, Georgian, Armenian, Lithuanian, Latvian, Estonian, Belarusian, Moldovan, Slovak, Slovenian, Austrian, Swiss, Icelandic, Maltese, Cypriot, Albanian, Bosnian, Macedonian, Montenegrin, Chilean, Ecuadorian, Paraguayan, Uruguayan, Bolivian, Honduran, Nicaraguan |
| `ethnicity` | `/api/v1/characters/ethnicities` | Aboriginal, Afghan, African-American, African-British, Afro-Indian, Afro-Latina, Afro-Puerto Rican, Albanian, Algerian, Arabian, Argentine, Armenian, Asian, Asian-mixed, Austrian, Barbadian, Bengali, Black, Bosnian, Brazilian, British, Bulgarian, Cambodian, Caucasian, Chinese, Chinese Taiwanese, Colombian, Croatian, Cuban, Cuban-American, Czech, Dominican, Dutch, Eastern European, Ebony, Egyptian, European, Filipina, Finnish, French, German, Ghanaian, Greek, Haida, Hispanic, Hmong, Hungarian, Indian, Indo-Fijian, Indonesian, Iranian, Irish-Italian, Israeli-Georgian, Italian, Italian-American, Jamaican, Japanese, Japanese-American, Kazakh, Kenyan, Korean, Korean-American, Kurdish, Latina, Lebanese, Malaysian, Maori, Mediterranean, Mexican, Middle-Eastern, Mixed Japanese, German, Irish & English, Mixed Race, Mixed Race - African-American & Caucasian, Mixed-Race, Mongolian, Moroccan, Native American, Nigerian, Nordic, Pakistani, Persian, Peruvian, Polish, Polynesian, Polynesian-Australian, Portuguese, Puerto Rican, Punjabi, Romani, Romanian, Scandinavian, Serbian, Slavic, South African, South Asian, Spanish, Swedish, Tamil, Thai, Trinidadian, Turkish, Ukrainian, Uyghur, Venezuelan, Vietnamese, Welsh, White |
| `hairLength` | `/api/v1/characters/hair-lengths` | Long, Very long, Shoulder-length, Medium, Short bob, Chin-length bob, Pixie cut, Short layered, Shaved sides + long top, Bald, Buzzcut, Asymmetrical bob, Undercut, Knee-length, Floor-length, Short crop, Pageboy, Shag, Mullet |
| `hairColour`, `hairColor` | `/api/v1/characters/hair-colours` | Ash Blonde, Auburn, Auburn Hair, Balayage Blonde, Bald, Black Hair, Black and White Hair, Blonde, Blonde Hair, Bronde, Brown Hair, Brunette, Burgundy, Butter Blonde, Caramel Brown, Champagne Blonde, Cherry Red Hair, Chestnut Brown, Chocolate Brown, Copper Red, Dark Brown, Dark Brown Hair, Dark brown Hair With Rose-Pink Ombre Tips, Dirty Blonde, Dyed, Fiery Red, Ginger, Ginger Hair, Golden Blonde, Gray Hair, Green Hair, Honey Blonde, Ice Blonde, Jet Black, Jet Black Hair, Light Brown, Mahogany, NA, Ombre, Pink And Blue Hair, Platinum Blonde, Platinum Blonde Hair, Purple Hair, Red Hair, Rose Gold, Silver, Strawberry Blonde, White Hair, Brown Hair |
| `eyeColour`, `eyeColor` | `/api/v1/characters/eye-colours` | Albino, Amber, Aqua, Blue, Blue Eyes, Bright Green, Brown, Brown Eyes, Central Heterochromi, Dark Blue Eyes, Dark Brown, Dark Brown Eyes, Deep Green, Emerald Green, Gold, Golden Brown, Green, Green Eyes, Grey, Grey Eyes, Grey-Blue, Grey-Green, Hazel, Hazel Eyes, Hazel-Green Eyes, Heterochromia, Honey Brown, Ice Blue, Light Blue, Light Brown Eyes, NA, Purple, Purple Eyes, Red Eyes, Sectoral Heterochromia, Silver Grey Eyes, Sky Blue, Steel Grey, Violet Eyes, Yellow |
| `skinTone` | `/api/v1/characters/skin-tones` | Light, Golden, Olive, Caramel, Medium Brown, Deep Tan, Very Pale, Deep Brown, Honey, Beige, Warm Ivory, Sun-Kissed, Pale Ivory, Warm Honey, Light Olive, Golden Olive, Light Caramel, Mocha, Rich Brown, Alabaster, Latte, Mahogany, Ebony, Espresso, Tawny, Tan |
| `bodyBuild`, `bodyType` | `/api/v1/characters/body-builds` | Amazon / tall & strong, Athletic, Athletic-Curvy, Average, BBW, Busty, Busty athletic, Busty hourglass, Buxom, Chubby, Curvy, Fat, Fit, Hourglass, Lean, Model-thin, Muscular, Muscular-athletic, NA, Pear shape, Petite, Petite hourglass, Skinny, Slender, Slim, Slim athletic, Soft & curvy, Tall Athletic Hourglass, Thick, Toned, Voluptuous |
| `bodyShape` | `/api/v1/characters/body-shapes` | Hourglass, Apple, Rectangle, Inverted triangle, Slim hourglass, Thick hourglass, Petite hourglass, Busty rectangle, Pear, Voluptuous hourglass, Chubby, Athletic, Soft pear, Top-heavy, Bottom-heavy pear, Balanced |
| `buttSize` | `/api/v1/characters/butt-sizes` | Athletic, Average, Big, Bubble Butt, Bulky, Firm & round, Flat, Heart-shaped, Huge, Jiggly, Juicy, Lean, Massive, Peach, Perky, Phat, Round, Round & Full, Shelf, Skinny, Small, Thicc, Thick, Wide |
| `breastSize` | `/api/v1/characters/breast-sizes` | 32B, 33D, 34 DDD, 34D, 36D, 38D, 38E, 43E, B Cup, Big Boobs, Big natural, C Cup, D Cup, DD, DDD, Extra Large, Firm, Full Boobs, Full natural, Huge Boobs, Large, Large Boobs, Large Fake, Massive Boobs, Medium, Medium Boobs, Perfect handful, Perky, Round augmented, Small, Small & perky, Small Boobs, Soft & full, Teardrop shape, Very perky, none |
| `breastPertness` | `/api/v1/characters/breast-pertness` | Perky, Firm, Natural, Full, Slightly Pendulous, Very perky, Teardrop shape, Round & firm, Soft & natural, Fake perky, Perfect teardrop, High & firm, Full but soft, Athletic, Gently sloping, Heavy, Fake round, Points outwards, Slightly sagging, Perfectly round implants, Torpedo, Wide Set perky, Small and super perky, Very Firm, Tubular |
| `nippleColour` | `/api/v1/characters/nipple-colours` | Light pink, Pink, Medium pink, Dark pink, Light brown, Medium brown, Dark brown, Rosy brown, Deep brown, Almost black, Peachy pink, Mauve, Tan brown, Reddish-pink, Dusky rose, Caramel brown, Puffy light pink, Puffy dark pink |
| `vaginaHair` | `/api/v1/characters/vagina-hair` | Bald, Designer, Diamond shape, French wax, Full bush, Heart shape, Landing strip, Lightning bolt, Long, Natural, Neat triangle, Partially shaved sides, Shaved, Small trimmed patch, Smooth wax, Thin landing strip, Thin vertical strip, Tiny Brazilian, Trimmed, Trimmed short, V shaped, Wild |
| `vaginaSize` | `/api/v1/characters/vagina-sizes` | Tight, Very tight, Super tight, Snug, Extremely tight, Slightly looser, Perfectly snug, Incredibly tight, Youthfully tight, Accommodating, Normal, Very Accommodating, Post-baby looser, Gripping, Relaxed, Well-used, Milf, Gilf, Loose & wet, Average, Petite tight |
| `penisSize` | None in v1 taxonomy endpoints | Small, Huge, Enormous |
| `orientation` | `/api/v1/characters/orientations` | 90/10, Asexual, Bi-curious, Bicurious, Bisexual, Demisexual, Experimenting, Fluid, Gay, Heteroflexible, Homoflexible, Lesbian, Mostly straight, Open to anything, Pansexual, Queer, Sapiosexual, Straight, Straight but plays with girls |
| `sexualExperience` | `/api/v1/characters/sexual-experiences` | Virgin, Almost virgin, Very limited, Moderate, Experienced, Very experienced, Highly experienced, 100+ partners, Former escort, Nymphomaniac, Porn-level, Innocent but curious, Only relationships, Mostly one-night stands, Lots of threesomes, Swinger, Recently awakened, Sheltered then wild, Reformed good girl, Always slutty |
| `relationshipStyle` | `/api/v1/characters/relationship-styles` | Monogamous girlfriend, Devoted housewife, Stay-at-home girlfriend, Open relationship / ENM, Trophy girlfriend, Free-use 24/7, Casual / FWB, Submissive girlfriend, Dominant girlfriend, Polyamorous (part of a V or triad), Sugar baby, Live-in slut, Long-distance girlfriend, Traditional 1950s dynamic, Brat tamed by you, Cuckquean (watches you with others), Hotwife (you watch her), Switch relationship, Collared / owned 24/7, Secret affair / side chick, Fiancee / soon-to-be wife, Newlywed wife, Breeding-focused monogamy, One-sided open (she's exclusive, you're not), Platonic-with-benefits (demi/ace) |
| `relationshipStatus` | `/api/v1/characters/relationship-statuses` | Single, In a relationship, Engaged, Married, Divorced, Widowed, It's complicated, Open relationship, Situationship, Single and looking, Single not looking, Taken but bored, Friends with benefits, Dating around, Exclusively yours |
| `personality` | `/api/v1/characters/personalities` | Active, Adaptable, Adventurous, Aggressive, Alluring, Ambitious, Artistic, Assertive, Athletic, Authentic, Blunt, Bold, Bookworm / quiet intellectual, Bratty, Bubbly, Bubbly & cheerful, Bubbly / genki, Calming, Caring, Caring mommy vibe, Charismatic, Charming, Cheeky, Classy, Compassionate, Confident, Confident boss babe, Creative, Cultured, Curious, Daddy's little princess, Dedicated, Demanding, Direct, Disciplined, Dominant, Dominant & teasing, Driven, Easy going, Easygoing, Educated, Emotional, Emotionally Deep, Empathetic, Empowering, Energetic, Engaging, Enterprising, Entrepreneurial, Expressive, Faith-driven, Fan-Focused, Flirtatious, Flirty, Flirty tease, Free-Spirited, Friendly, Fun, Fun-loving, Funny, Generous, Gentle, Genuine, Girl-next-door, Glamourous, Gothic / alt girl, Graceful, Grounded, High-Energy, High-maintenance diva, Himbo-level ditzy, Honest, Humble, Humorous, Hyper horny nympho, Ice queen (melts for you), Independent, Insightful, Intelligent, Introspective, Introverted, Intuitive, Kind, Laid-back, Likeable, Low-maintenance chill, Loyal, Luxury-Embracing, Mentor, Mindful, Mischievous, Mysterious, Naughty, Nerdy, Nerdy / gamer girl, Noble, Nurturing, Observant, Obsessed / clingy, Open, Open-minded, Optimistic, Organized, Outdoorsy, Outgoing, Passionate, Patient, Perfection Driven, Playful, Polite, Positive, Private, Quiet, Rebellious, Reflective, Reformed good girl, Reliable, Reserved, Resilient, Resourceful, Responsible, Romantic, Sarcastic, Sassy & sarcastic, Seductive, Sensual, Sexy, Shy, Shy & submissive, Sociable, Social, Sophisticated, Spirited, Spiritual, Spoiled princess, Spontaneous, Strong, Strong-willed, Submissive, Subordinate, Supportive, Sweet & innocent, Teasing, Total bimbo, Truthful, Tsundere, Unapologetic, Unapologetically Confident, Unstoppable, Uplifting, Versatile, Versitile, Vibrant, Virgo, Visionary, Vulnerable, Warm, Warm-hearted, Wild, Wise, Witty, Yandere, Youthful, affectionate, candid, hedonistic, intellectually curious, loving, organised, outspoken, self-reliant, upbeat |
| `sexDrive` | `/api/v1/characters/sex-drives` | Very high, Hypersexual nympho, High, Always horny, Average, Touch-starved, Insatiable, High but shy, Moderate, Low until aroused then wild, Once a day minimum, Morning sex addict, Only horny when ovulating, Switches normal to crazy, Low, Permanently in heat, Night owl horny, Needs it to fall asleep, Very low cuddly, Asexual but enjoys pleasing |
| `conversationStyle` | `/api/v1/characters/conversation-styles` | Flirty & teasing, Sweet & innocent, Bratty & sassy, Shy & soft-spoken, Bubbly & giggly, Dirty talk queen, Proper & polite, Valley girl, Weeb / anime speech, Tsundere, Baby-talk / little space, Foul-mouthed & trashy, Sarcastic & witty, Submissive & obedient, Dominant & commanding, Low-key & chill, Constant compliments & praise, Nerdy & rambling, High-maintenance princess, Country / southern drawl |
| `attitude` | `/api/v1/characters/attitudes` | Sweet & innocent, Bratty, Bubbly & cheerful, Shy & submissive, Flirty tease, Tsundere, Yandere, Spoiled princess, Confident boss babe, Nerdy gamer girl, Ice queen, Sassy & sarcastic, Clingy & obsessed, Dominant & commanding, Girl-next-door, Gothic / alt, Ditzy bimbo, Caring mommy, High-maintenance diva, Low-key chill |
| `gender` | None in v1 taxonomy endpoints | Female, Male |
| `contentLevel` | None in v1 taxonomy endpoints | Sexy, Topless, Nudes, Sex |

## Digital Twins

Digital twin endpoints create, update, retrieve, and regenerate media for creator-based profiles.

### Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/digital-twins/check-celebrity` | Check if an image contains a celebrity likeness. |
| `POST` | `/api/v1/digital-twins` | Create a digital twin. |
| `PATCH` | `/api/v1/digital-twins/{digitalTwinId}` | Update a digital twin. |
| `POST` | `/api/v1/digital-twins/{digitalTwinId}/profile-image-with-cover-video` | Save a profile image and generate a cover video. |
| `GET` | `/api/v1/digital-twins/status/{digitalTwinId}` | Get digital twin status. |
| `GET` | `/api/v1/digital-twins/customer-digital-twins` | Get digital twins for the authenticated customer. |
| `GET` | `/api/v1/digital-twins/{characterId}` | Get a digital twin by legacy character ID. |

### Create Digital Twin Request

Required fields: `name`, `alias`, `dateOfBirth`, `job`, `location`, `gender`, `orientation`, `hairColour`, `eyeColour`, `bodyType`, `referenceImageUrl`, `contentLevel`.

| Field group | Fields |
| --- | --- |
| Identity | `name`, `alias`, `dateOfBirth`, `gender` |
| Profile | `job`, `location`, `bio`, `textingStyle`, `contentLevel`, `backstory` |
| Physical attributes | `ethnicity`, `hairColour`, `eyeColour`, `bodyType`, `hairLength`, `breastSize`, `tattoos`, `vaginaHair`, `physicalCharacteristics` |
| Preferences | `orientation`, `personality`, `interests`, `kinks`, `extraDetails`, `relationshipStatus` |
| Prompts | `roleplayPrompts`, `flirtingPrompts`, `imageRequestPrompts`, `profileImagePrompts` |
| Media | `referenceImageUrl`, `profileImageUrl`, `coverVideoUrl`, `voiceUrl`, `audioSpeed` |
| Social handles | `socialHandleInstagram`, `socialHandleTiktok`, `socialHandleTwitter`, `socialHandleYoutube`, `socialHandleTwitch`, `socialHandleTelegram` |

### Update Digital Twin Request

All create fields can be updated except immutable ownership fields, depending on partner permissions.

### Profile Image Prompt Item

```json
{
  "label": "Portrait",
  "prompt": "Close-up portrait prompt"
}
```

## Customer Library

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/v1/customer-library` | Get saved characters and digital twins for the authenticated customer. |

## Conversation Rooms

Rooms bind a client, user, character, and conversation history. A room carries the context used by text, audio, image, and video endpoints.

Only one room per client, user, and character should be active at a time. Creating a room deactivates sibling rooms for the same user and character.

### Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/rooms` | Create a room. |

### Create Room Request

Required field: `character_id`.

| Field | Description |
| --- | --- |
| `character_id` | Character identifier. |
| `user_id` | Client-side user identifier. |
| `user` | Nested user profile. |
| `ip` | User IP address, if available. |
| `user_gender` | Legacy user gender field. Maps to `user.gender`. |

Example:

```json
{
  "character_id": "12345",
  "user_id": "user_789",
  "user": {
    "name": "Alex",
    "gender": "male"
  }
}
```

Response:

```json
{
  "room_id": "room_123"
}
```

### User Object

Optional fields: `name`, `age`, `gender`, `location`, `orientation`, `ab_experiment_group`.

## Text Replies

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/text` | Generate a synchronous text reply. |

### Text Generation Request

Use either a `room_id` for room-aware generation or direct `character_id`, `history`, and `user` fields for a stateless-style request.

| Field | Description |
| --- | --- |
| `room_id` | Room identifier. |
| `character_id` | Character identifier. |
| `history` | Prior turns as `{ role, content }` objects. |
| `user` | User profile object. |
| `prompt` | User prompt. May be empty for an opening-message flow. |
| `audio_input_url` | URL of a user voice note. The transcript should be carried in `prompt`. |

Response fields: `content`, `job_id`, `message_id`, `tool_call`.

## Audio Replies

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/audio/notes` | Generate a synchronous spoken reply for a room or character context. |

### Audio Generation Request

Fields: `room_id`, `character_id`, `history`, `user`, `prompt`, `audio_input_url`.

The room's character voice is used for room-based audio replies. `prompt` may be empty for an opening-message flow.

Response fields: `url`, `job_id`, `message_id`, `content`, `tool_call`.

## Jobs

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/v1/jobs/{job_id}/status` | Poll an async job's status and result URL. |

### Job Status Response

Fields: `job_id`, `status`, `url`, `results`, `error`.

`status` is one of `queued`, `processing`, `completed`, or `failed`.

`results` may include:

| Field | Description |
| --- | --- |
| `image_prompt` | Final image prompt used by the worker. |
| `detected_level` | Server-detected content level. |
| `followup_text` | Follow-up message text. |
| `content` | Generated content payload. |

## Image Generation

### Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/images` | Generate an image asynchronously. Supports direct character generation or room-aware generation. |

### Generate Image Request

Use `character_id` for direct character image generation, or `room_id` for history-aware in-room generation.

| Field | Description |
| --- | --- |
| `prompt` | Image prompt. Required for most direct generation flows. |
| `character_id` | Character identifier. |
| `room_id` | Room identifier for in-room generation. |
| `user` | User profile object. |
| `prompt_enhancement` | Whether server-side prompt enhancement should be used. |
| `style` | Look of the picture when `prompt_enhancement` is true: `glam` (default) or `amateur`; any other value returns 400. Ignored for a character created with `style: "artificial"`, which always renders in its own artificial look and reports `results.style: "artificial"` — `"artificial"` is not a value you can send here. |
| `user_gender` | Legacy user gender field. |
| `resolution` | Output resolution. Accepts `[width, height]` or aspect ratio string such as `9:16`, `16:9`, `1:1`, `4:3`, or `3:4`. |

Response fields: `message`, `job_id`, `status`, `presigned_url`, `message_id`.

## Videos

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/videos/create` | Generate a video asynchronously. Supports text-to-video, image-to-video, and in-room generation. |
| `POST` | `/api/v1/videos/t2v-pro` | Generate an explicit video of a character from a text prompt. |
| `GET` | `/api/v1/videos/get` | Get video status and URL. |
| `DELETE` | `/api/v1/videos/delete` | Delete a video. |

### Create Video Request

Use `character_id` for text-to-video from a character, `image_url` for image-to-video from an existing image, or `room_id` for history-aware in-room generation.

| Field | Description |
| --- | --- |
| `prompt` | Video prompt. |
| `character_id` | Character identifier for text-to-video generation. |
| `room_id` | Room identifier for in-room generation. |
| `user` | User profile object. |
| `image_url` | Source image URL for image-to-video generation. |
| `prompt_enhancement` | Whether server-side prompt enhancement should be used. |
| `resolution` | Output resolution. |
| `length` | Requested video length in seconds. |

Response fields: `message`, `job_id`, `status`, `presigned_url`, `message_id`.

### Explicit Video (t2v-pro) Request

Required fields: `prompt`, `character_id`.

The character must be accessible to your account, allow explicit (level 4) content, and be female. The first frame is rendered from your prompt, then animated.

| Field | Description |
| --- | --- |
| `prompt` | What should happen in the video, in any language. |
| `character_id` | Character to star in the video. |
| `length` | Video length in whole seconds, 2 to 30. Defaults to 5. Billed per second. |
| `prompt_enhancement` | Whether server-side prompt enhancement should be used. `false` sends the prompt as written. |
| `style` | Look of the first frame: `glam` (default) or `amateur`. |
| `position` | Sex position to show. Omit to have it chosen from the prompt. |

Response fields: `message`, `job_id`, `status`, `presigned_url`.

Poll `GET /api/v1/jobs/{job_id}/status`. `results.first_frame_url` is available before the video is finished; `url` is set once `status` is `completed`. A 5s video takes about 2-3 minutes, 30s about 9-10 minutes, and jobs queue rather than fail when capacity is full.

### Legacy Video Status/Delete Fields

Some compatibility endpoints use the older video request terminology:

| Field | Description |
| --- | --- |
| `imageUrl` | Source image URL. |
| `prompt` | Video generation prompt. |
| `category` | Video category. |
| `videoPath` | Destination or reference path. |
| `videoLength` | Requested video length. |

## Profile Extraction

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/profile-extraction/extract` | Extract a creator profile from an interview transcript. |

### Extract Profile Request

Required fields: `creatorId`, `transcript`.

```json
{
  "creatorId": "creator_123",
  "transcript": [
    {
      "role": "interviewer",
      "message": "Tell me about your style.",
      "time_in_call_secs": 12
    }
  ]
}
```

### Transcript Entry

Required fields: `role`, `message`.

Optional field: `time_in_call_secs`.

## Voices

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/v1/voices` | Get default voices. |
| `GET` | `/api/v1/voices/elevenlabs` | Get popular public ElevenLabs voices. |

## Face Similarity

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/face-similarity/compare` | Compare two faces for 1:1 verification. |
| `POST` | `/api/v1/face-similarity/embed` | Embed a single face. |

### Compare Face Request

Required fields: `image_a_url`, `image_b_url`.

| Field | Description |
| --- | --- |
| `image_a_url` | First image URL. |
| `image_b_url` | Second image URL. |
| `threshold` | Optional verification threshold. |
| `request_id` | Optional caller-provided request identifier. |

### Embed Face Request

Required field: `image_url`.

Optional field: `request_id`.