API documentation
Everything you need to integrate chat, voice, image, video, cams and Digital Twins through one API.
Choose a feature. Copy its prompt. Build.
You do not need to read the whole API reference. Pick what you want to make and paste one complete build prompt into your coding tool.
- 01
Choose a feature
Chat, images, video, characters, or a complete playground.
- 02
Copy one prompt
It includes the exact API flow and security requirements.
- 03
Paste and build
Use it in Cursor, Lovable, Bolt, v0, or ChatGPT.
One rule before you start
Keep OH_API_KEY on your server. Never expose it in browser code.
Start here
What are you building?
One click copies complete implementation instructions. Paste them into Cursor, Lovable, Bolt, v0, or ChatGPT.
Character chat
A secure, stateful chat with saved characters and digital twins.
Image generation
Generate a character image and show progress until it is ready.
Video generation
Support character-to-video and image-to-video with correct polling.
Character creator
Generate, review, and save an AI character through the v2 workflow.
Full media playground
One app for chat, audio, image, and video generation.
If your coding tool cannot open links, copy the full API context from the top of this page first.
Optional
Prefer to wire it yourself?
Skip this section if you are using one of the build prompts above.
import "server-only";
const 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.set("Content-Type", "application/json");
const response = await fetch(BASE_URL + path, {
...init,
headers,
cache: "no-store",
});
if (!response.ok) {
const body = await response.text();
throw new Error("Oh API " + response.status + ": " + body);
}
return response.json() as Promise<T>;
}curl --fail-with-body --show-error --silent -X POST "https://api.oh.xyz/api/v1/rooms" \
-H "X-API-Key: $OH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"character_id": "12345",
"user_id": "user_789",
"user": { "name": "Alex" }
}'API Overview
Oh API is a JSON REST API for character creation, digital twins, conversation rooms, text and audio replies, and generated media. Public operations live under /api/v1 and /api/v2.
Production base URL
https://api.oh.xyzStart integrating
Generate a key, then send your first request without writing any code.
Core API concepts
Two things to understand before your first integration: which calls return immediately, and which identifier belongs where.
Synchronous operations
Text and audio calls return their result in the request response. Do not start a polling loop for them.
Asynchronous operations
Image and video calls return an ID. Poll the matching status endpoint until the operation completes or fails.
Identifier guide
Keep these distinctcharacterId- Saved character used by chat and media endpoints.
characterGuid- Temporary v2 generation and save workflow identifier.
digitalTwinId- Digital-twin resource identifier.
userId- Your user identifier for room-scoped resources.
room_id- Conversation context shared by chat and media requests.
message_id- A stored message that can be updated or regenerated.
job_id- Asynchronous image or video generation job.
Authentication
Partner endpoints require an API key on every request. Send it over HTTPS from trusted server code.
Server-only is the security boundary
Never place an Oh API key in client-side JavaScript, mobile bundles, local storage, public environment variables, URLs, or logs. Route requests through your backend or a narrow server-side proxy.
Environment
Add this to the server's secret configuration.
OH_API_KEY=replace_with_your_api_keyNever prefix it with NEXT_PUBLIC_ as that ships the key to the browser.
Request headers
Attach these to server-to-server requests.
X-API-Key: <api_key> Content-Type: application/json
A missing or revoked key returns 401.
Keys are created and revoked from your dashboard.
Create or manage an API keyImplementation patterns
These rules prevent the most common integration failures and keep the behavior predictable across chat and media features.
Protect the key
Make Oh API calls from trusted server code. Expose only the minimum routes your client needs.
Reuse rooms
Keep one room per user and character conversation. A new room per message discards useful context.
Know sync from async
Text and audio return immediately. Images and videos require a status flow.
Retry deliberately
Retry transient 5xx responses with backoff. Do not automatically retry validation or moderation failures.
Surface actionable errors
Preserve the upstream status and response body for developers, but redact credentials. A moderation rejection or malformed body needs a user correction; a transient service failure may be retried.
Async media pattern
- 1Submit onceSend the image or video request and store the returned job or resource identifier.
- 2Poll with a limitCheck the matching status endpoint every 2–5 seconds and stop after five minutes.
- 3Handle both terminal statesStop on completed or failed. Show the upstream error when generation fails.
- 4Use the final URLRender or persist the url returned by the completed status response. Poll again if an expiring URL needs to be refreshed.
Ready to build
Generate a key, then try the flow end to end without writing code.
HTTP Status Codes
Standard Responses
Error Format
All errors return JSON with an error message and may include additional diagnostics:
{
"error": "Error description",
"message": "Optional human-readable details",
"suggestion": "Optional next step"
}Common Errors
See these responses live
Fire a real request in the playground and inspect the status codes it returns.
Reference
API endpoints
Use this section when you need exact request fields or response shapes. Endpoints stay collapsed until you open them.
Customer Library
Customer library endpoints return the authenticated customer's saved characters and digital twins. Authenticate with your API key in the x-api-key header.
Media APIs
Explicit Image & Video Prompt Examples
The OH API provides support for explicit adult content generation across all 25 currently available video types for video generation. The examples below use only image prompts that have been playground tested, with matching video prompt examples shown when available. All explicit content generation is restricted to verified adult platform partners and requires a validated API key with adult content permissions enabled.
Show prompt examples
14 tested examples and 25 supported video types
Show prompt examples
14 tested examples and 25 supported video types
Prompt enhancement is available for video generation
Set prompt_enhancement to true when creating a video to have the API expand shorter prompts into a more descriptive generation prompt before rendering.
Explicit image prompts: raw prompt vs. prompt enhancement
The image prompts below are written to be sent as-is with prompt_enhancement: false. With prompt_enhancement: true, an explicit (level 4) image request is instead rendered around a sexual position: the position is detected from your prompt (or fixed with the optional position field), the pose follows that position rather than every detail of the wording, the place you name is honoured, and the optional style (glam or amateur) decides how it is shot. See Image styles and explicit-level rendering. Note that the image position names differ from the video type names listed here.
Available video types
Image Prompt
Photograph of the same woman. The woman is naked and kneeling in front of a man. The woman is performing oral sex on the man's erect penis. She is looking up to the man while sucking his penis.
Video Prompt
Explicit deep blowjob animation, full detailed view of both man and woman. A beautiful young woman kneels submissively on the carpet in a luxurious hotel bedroom, passionately sucking a muscular man's rock-hard rigid fully erect penis. She bobs her head deeply from tip to base with visible throat bulge on every stroke, thick glossy saliva pouring from her stretched lips and forming long dripping strings that coat the shaft and balls. Excessive messy spit play, saliva running down her chin onto her breasts. Intense upward eye contact with teary eyes and lustful expression. The penis stays steel-hard, throbbing, and maximally erect the entire clip — never soft, never limp, prominent bulging veins, swollen glistening glans. Smooth 24fps animation, hyper-realistic saliva physics, natural motion blur, glossy wet surfaces, flawless anatomy, cinematic hotel lighting, masterpiece quality.
Image Prompt
Photograph of the same woman. The woman is naked and kneeling in front of a man. Pov shot from the man's persepctive. The woman is performing oral sex on the man's erect penis. She is looking up to the man while sucking his penis
Video Prompt
Explicit blowjob animation, full detailed view of both man and woman. A beautiful young woman kneels and sucks a muscular man's rock-hard rigid fully erect penis deeply with rhythmic bobbing and visible throat bulge. Thick saliva drips heavily down the shaft. Intense upward eye contact. The penis stays steel-hard and throbbing the entire clip. Smooth 24fps animation, hyper-realistic saliva physics, flawless anatomy, masterpiece quality.
Image Prompt
Photograph of the same woman. She is naked in a gangbang bukkake scene surrounded by five men standing around her. There are five erect penises visible, she is holding two, each in her hands. She kneels in the center with semen covering her face, breasts, and mouth open. She is looking into the camera with a satisfied expression. The background is an underground club with red velvet background and red lights.
Image Prompt
Photograph of the same woman. The woman is naked and she is on top of a naked men. The man sits on a red leather sofa. The woman is on top of the man. She is riding him in cogwirl position. The woman grinds his vagina into the mans erect penis. The woman's ass is visible, she is facing the man. The woman is looking back at the camera.
Video Prompt
Intense cowgirl sex animation, full detailed view of both man and woman. A beautiful young woman straddles a muscular man lying on his back on a large king bed, riding his rock-hard rigid fully erect penis with powerful up-and-down bouncing. She lifts her hips high until only the swollen head stretches her labia, then slams back down taking him balls-deep. Clear visible in-and-out penetration, stretched labia gripping the shaft, shiny wetness and creamy fluids coating the cock. Her full breasts bounce heavily with realistic jiggle and rebound, erect nipples. Strong downward eye contact, ecstatic open-mouth expression. The penis stays steel-hard, throbbing, and maximally erect the entire clip — never soft. Smooth 24fps animation, realistic breast and hip physics, glossy wetness, natural motion blur, flawless anatomy, luxurious hotel lighting, masterpiece quality.
Image Prompt
Photograph of the same woman. She is naked and lying on her back on a bed. Her legs are spread. There is a male's head between her legs and he is licking the woman's vagina. Only the male's head is visible.
Video Prompt
Intense cunnilingus animation, full detailed view of both man and woman. A beautiful young woman lies on her back on a large hotel bed, legs spread maximally wide and pulled back toward her chest. A strong muscular man is positioned between her thighs, eagerly performing cunnilingus with deep tongue strokes, licking and sucking her swollen clit and wet labia. Visible arousal fluids dripping down his chin and onto the sheets. The woman's body arches and trembles in pleasure, full breasts heaving and bouncing naturally, mouth open moaning loudly, eyes half-closed in ecstasy. The man's rock-hard rigid fully erect penis is clearly visible below, steel-hard and throbbing — never soft. Smooth 24fps animation, hyper-realistic tongue and pussy physics, glossy wetness, realistic breast movement, flawless anatomy, warm hotel lighting, masterpiece quality.
Image Prompt
Photograph of the same woman. She is naked and on top of a man. The woman's vagina is positioned above the mans' mouth. The man is licking the woman's vagina while she is sitting on her face. The man lies on his back on a bed. She is looking into the camera with intense eyes.
Image Prompt
Intimate solo image of a beautiful woman lying on her back with legs spread wide, masturbating with one hand touching her wet vulva and clitoris while her other hand rests on her breast. Her face is visible and turned slightly toward the camera with a soft, sensual, glamorous expression. No other person and no penis are present in the frame.
Image Prompt
Explicit group sex: a beautiful woman on all fours between multiple men, face soft and glamorous. She takes a large thick erect penis in her mouth while another man enters her from behind in doggy-style; more men frame her with erect penises visible, her face never hidden. She looks up with a sensual expression.
Image Prompt
Photograph of the same woman. She is naked and giving a handjob to a man's erect penis. She is kneeling in front of him with both hands wrapped around his shaft, stroking firmly. She is looking into the camera with a seductive smile. The background is a steamy hot tub on a rooftop at night with city skyline lights, bubbles rising, and steam in the air.
Video Prompt
Intense handjob animation, full detailed view of both man and woman. A beautiful young woman kneels and uses both hands to firmly stroke a muscular man's rock-hard rigid fully erect penis with fast rhythmic motions. Fingers wrapped tightly around the thick shaft, sliding up and down the full length, twisting slightly, palms and fingers glossy with precum. Intense upward eye contact with desire. The penis stays steel-hard and throbbing the entire clip — never soft. Smooth 24fps animation, realistic hand physics, glossy wetness, flawless anatomy, masterpiece quality.
Image Prompt
Photograph of the same woman. The woman is lying on her back naked on a red sports car, with her legs spread. A man is positioned above her, and he is inserting his erect penis into the woman's vagina. Only the man's penis is visible. POV shot from the man's perspective
Video Prompt
Hard intense missionary sex animation, full detailed view of both man and woman. A beautiful young woman lies on her back on a large king-size bed, legs spread wide and pulled back toward her chest. A strong muscular man is on top of her, thrusting his rock-hard rigid fully erect penis deep into her vagina with powerful in-and-out strokes — pulling out almost completely then slamming balls-deep with force. Heavy creamy wetness coats the shaft, labia stretched and gripping tightly. The woman's full breasts bounce heavily up and down with realistic physics, mouth open moaning, strong eye contact. The penis stays steel-hard, throbbing, and maximally erect the entire clip — never soft. Smooth 24fps animation, realistic breast physics and vaginal grip, glossy wetness, flawless anatomy, luxurious hotel lighting, masterpiece quality.
Image Prompt
Photograph of the same woman. The woman is naked, she has small breasts and shaved pubes. The woman is sitting on a naked man. The man is sitting on a red couch. The man is holding up the naked woman's legs in the air, exposing her vagina. The man is penetrating the womans vagina with his erect penis, while he is holding the woman's legs in the air. The man is behind the woman, his face is not visible.
Video Prompt
Intense reverse cowgirl sex animation, full detailed view of both man and woman. A beautiful young woman straddles a muscular man facing away, riding his rock-hard rigid fully erect penis with strong up-and-down bouncing. Clear visible in-and-out penetration from behind, ass cheeks spreading and rippling, heavy wetness. Breasts bouncing forward. The penis stays steel-hard and throbbing the entire clip. Smooth 24fps animation, realistic ass and breast physics, glossy wetness, flawless anatomy, masterpiece quality.
Image Prompt
External three-quarter view of a beautiful woman having standing sex from behind. She stands leaning slightly forward while a man stands directly behind her, gripping her waist as his large thick erect penis enters her vagina from behind. Her back is arched, bum visible, and the exact vaginal penetration point is clearly visible between her thighs. She turns her face partly toward the camera with a soft, sensual, glamorous expression. This is explicit vaginal penetrative sex.
Video Prompt
Hard standing sex from behind animation, full view of both man and woman. A beautiful young woman is bent slightly forward while a muscular man stands behind her, thrusting his rock-hard rigid fully erect penis into her vagina with fast rhythmic strokes. Clear in-and-out penetration, legs spread, breasts bouncing vertically with every impact. Strong eye contact over the shoulder. The penis stays steel-hard and throbbing the entire clip. Smooth 24fps animation, realistic motion and breast physics, glossy wetness, flawless anatomy, masterpiece quality.
Image Prompt
Photograph of the same woman. She is naked performing oral sex on one man's erect penis, who is in front of her. Another man is behind her and penetrates her vagina from behind in a doggy position. She is naked and kneeling on all fours.
Video Prompt
Intense MMF threesome animation, full detailed view of all three people. A beautiful young woman is between two muscular men on a large hotel bed. One man thrusts his rock-hard rigid fully erect penis deep into her vagina from behind with powerful strokes, while the second man receives a deep blowjob from her. Clear in-and-out motion in her pussy, breasts bouncing wildly from dual stimulation, ecstatic expressions. Both penises stay steel-hard and throbbing the entire clip — never soft. Smooth 24fps animation, glossy wetness, realistic body physics, flawless anatomy, luxurious hotel lighting, masterpiece quality.
Image Prompt
Photograph of the same woman. Close up shot of the womans breasts. The woman is naked and kneeling in front of a man. Her hands push her breasts together. The mans erect penis is pressed against her cleavage. POV shot from the man's perspective. The man's penis is in between the woman's breasts. She is also holding her breasts and the penis.
Video Prompt
Intense titjob animation, full detailed view of both man and woman. A beautiful young woman presses her full breasts together around a muscular man's rock-hard rigid fully erect penis, sliding them up and down the lubricated shaft in rhythmic motion. Erect nipples brush the head, skin glossy with lubrication. Upward aroused eye contact. The penis stays steel-hard and throbbing the entire clip — never soft. Smooth 24fps animation, realistic breast physics, glossy wetness, flawless anatomy, masterpiece quality.