---
title: "Create Digital Twin"
method: POST
path: "/api/v1/digital-twins"
tags: ["Digital Twins"]
---

# Create Digital Twin

`POST /api/v1/digital-twins`

Creates a new digital twin character. Processing happens asynchronously. Poll the status endpoint to track completion.

## Request body

- CreateDigitalTwinRequest
  - `name` string, required — Character display name
  - `alias` string, required — Character nickname / short name
  - `dateOfBirth` string, date, required — Date of birth (ISO format). Character must be 21+
  - `job` string, required — Character occupation
  - `location` string, required — Where the character lives
  - `gender` Gender, required — unresolved $ref
  - `orientation` Orientation, required — unresolved $ref
  - `hairColour` string, required — Hair colour. Use GET /api/v1/characters/hair-colours for valid values
  - `eyeColour` string, required — Eye colour. Use GET /api/v1/characters/eye-colours for valid values
  - `bodyType` string, required — Body type. Use GET /api/v1/characters/body-builds for valid values
  - `referenceImageUrl` string, uri, required — URL to reference image (downloaded and saved to S3)
  - `contentLevel` ContentLevel — unresolved $ref
  - `profileImageUrl` string, uri — URL to profile image (converted to PNG and saved)
  - `bio` string — Character biography
  - `textingStyle` string — Texting/communication style
  - `ethnicity` string — Character ethnicity. Use GET /api/v1/characters/ethnicities for valid values
  - `hairLength` string — Hair length. Use GET /api/v1/characters/hair-lengths for valid values
  - `breastSize` string — Breast size (female only). Use GET /api/v1/characters/breast-sizes for valid values
  - `tattoos` string — Tattoo description
  - `physicalCharacteristics` string[] — Physical characteristics (array of strings)
  - `personality` string[] — Personality traits. Values must match valid terms — use GET /api/v1/characters/personalities for the full list
  - `interests` string[] — Character interests. Values must match valid terms — use GET /api/v1/characters/interests for the full list
  - `kinks` string[] — Character kinks. Values must match valid terms — use GET /api/v1/characters/kinks for the full list
  - `audioSpeed` number, float — Audio playback speed multiplier
  - `socialHandleInstagram` string — Instagram handle
  - `vaginaHair` string — Pubic hair style (female only). Use GET /api/v1/characters/vagina-hair for valid values
  - `relationshipStatus` string — Relationship status
  - `backstory` string — Character backstory. Auto-generated if not provided
  - `coverVideoUrl` string, uri — URL to cover video (downloaded and saved to S3)
  - `voiceUrl` string, uri — HTTP URL to voice reference audio file (.wav). For best results, ~30 seconds of clear speech
  - `socialHandleTiktok` string — TikTok handle
  - `socialHandleTwitter` string — X/Twitter handle
  - `socialHandleYoutube` string — YouTube handle
  - `socialHandleTwitch` string — Twitch handle
  - `socialHandleTelegram` string — Telegram handle
  - `earlyAccessEmail` integer — Early access email entity reference
  - `priorityPrice` number, float — Priority subscription price (field_sub_a)
  - `platinumPrice` number, float — Platinum subscription price (field_sub_b)
  - `vipPrice` number, float — VIP subscription price (field_sub_c)
  - `priorityListPrice` number, float — Priority list price (field_list_price_a)
  - `platinumListPrice` number, float — Platinum list price (field_list_price_b)

## Response `201`

Digital twin creation started. Poll status endpoint for completion.

- object
  - `success` boolean
  - `digitalTwinId` string, uuid — Digital twin UUID for status polling
  - `status` 'pending' | 'active' | 'draft' | 'inactive' — Digital twin processing status: - **pending**: Creation/update in progress - **active**: Digital twin is ready and live - **draft**: Initial state before processing - **inactive**: Deactivated
  - `message` string

## Other responses

- `400` — Validation error - missing required fields or character under 21
- `401` — Unauthorized - invalid or missing API key
- `500` — Server error - image download failed or database error

---

[API](https://skmtc.dev/oh/apis/ohapi-documentation.md) · [All operations](https://skmtc.dev/oh/apis/ohapi-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/oh/ohapi-documentation/revisions/b623c2e9cb65/schema)