spicyapi-com Live calls API

openapi: 3.2.0
info:
  title: Spicy Live calls API
  version: 1.0.0
  description: 'Spicy API (also written SpicyAPI) is one REST API for uncensored image, image-editing, video, video-editing, speech, live voice call, transcription, embedding and chat generation, sold per generation from a prepaid US-dollar balance: no subscription, no GPUs to run. It is OpenAI-compatible (point the OpenAI SDK at https://api.spicyapi.com/v1 with a Spicy API key) and includes ready-made sex actions for video and role-play companion models. It has been at spicyapi.com since June 2025, is operated by Wayfinity Ltd, and is not affiliated with spicyapi.ai, an unrelated model aggregator. Images from $0.06, video from $0.05 per second. OPENAI-COMPATIBLE: point the OpenAI SDK at https://api.spicyapi.com/v1 with a Spicy API key; client.images.generate maps onto POST /v1/images/generations and client.chat.completions.create onto POST /v1/chat/completions (streaming included). client.embeddings.create maps onto POST /v1/embeddings and client.audio.transcriptions.create onto POST /v1/audio/transcriptions. Image edits take JSON with image_url (not the SDK''s multipart upload) and video (generations, edits, motion transfer) is a plain HTTP task you poll. Every response carries cost_usd, the exact amount debited. Prompts are screened before any charge (422, never billed); failed generations are refunded. Sandbox keys (created with sandbox: true) answer every endpoint from fixtures flagged sandbox: true and bill nothing. Machine-readable overview: https://www.spicyapi.com/llms.txt. MCP server for agents: https://www.spicyapi.com/api/mcp.'
  contact:
    name: Spicy API support
    email: contact@spicyapi.com
    url: https://www.spicyapi.com/docs
  termsOfService: https://www.spicyapi.com/terms-of-service
servers:
- url: https://api.spicyapi.com
  description: Public API host (also reachable at https://www.spicyapi.com/api).
tags:
- name: Live calls
paths:
  /v1/realtime/sessions:
    post:
      operationId: createRealtimeSession
      summary: Create Live Call Session
      description: 'Start a live voice call with a companion: returns a one-time WebSocket URL your client (a browser too) connects to, without ever seeing your API key. `spicy-live-1`: the caller talks, the persona answers in a natural voice, and interruptions are handled, over one WebSocket (`wss://api.spicyapi.com/v1/realtime`, see Live Call WebSocket). Set the persona and voice here; the call itself follows the OpenAI Realtime event shape. `spicy-live-2` is the highest-quality live call: the role-play model `spicy-companion-1` writes every reply (it stays in the scene and moves it forward), spoken by Spicy Voice 3 voices that act the emotion (`Bella Bright`, `Roger`, `Sarah`, `Laura`, `Charlie`, `George`, `Callum`, `River`, `Harry`, `Liam`, `Alice`, `Matilda`, `Will`, `Jessica`, `Eric Smooth`, `Chris`, `Brian`, `Daniel`, `Lily`, `Adam`, `Bill`, default `Sarah`), with turn-taking and interruptions handled for you. Same WebSocket events and audio formats as `spicy-live-1`. It takes `language` (`en`, `zh`, `de`, `it`, `pt`, `es`, `ja`, `ko`, `fr`, `ru`, default English) and no `turn_detection`. Billed at $0.08 per minute of call time (by the second) plus the reply tokens at $1.00 in, $2.80 out per 1M tokens; each charge arrives as a `spicy.usage` event. Opening a session needs a balance of at least $0.10. The ticket in `client_secret.value` works once, within 60 seconds. Create the session on your server with your key and hand only the returned `url` to the browser. A call lasts up to 780 seconds per session; open a new session to continue. Billed per turn from the tokens each reply used, per 1M tokens: text in $0.46, audio in $1.86, text out $1.40, audio out $3.74. Audio counts about 7 tokens per second in and 12.5 out, and the conversation so far is billed again as input on each turn, which comes to about 1 to 1.5 cents per minute of steady back-and-forth (measured on real calls, Oct 2026; less when the line is quiet). Opening a session needs a balance of at least $0.05; when the balance or your spend limit runs out mid-call, the call ends with a `payment_required` error event. The persona in `instructions` is screened like a prompt before the session is created (422 when blocked). During the call both sides'' transcripts are screened; a violation ends the call with a `content_blocked` error event. No custom or cloned voices, no camera or image input, no tools or web search. Sandbox keys get a session whose socket answers with canned events and bills nothing. Calls appear in the request log as type `realtime` with seconds, turns and total cost.'
      tags:
      - Live calls
      security:
      - apiKey: []
      responses:
        '200':
          description: Session
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Session id, `rt_...`.
                  object:
                    type: string
                    description: Always `realtime.session`.
                  model:
                    type: string
                    description: The model.
                  voice:
                    type: string
                    description: The voice that answers.
                  turn_detection:
                    anyOf:
                    - type: object
                    - type: 'null'
                    description: The turn detection in effect.
                  max_seconds:
                    type: integer
                    description: Longest call on this session.
                  input_audio:
                    type: string
                    description: 'What to send: PCM16 mono 16 kHz, base64, in `input_audio_buffer.append`.'
                  output_audio:
                    type: string
                    description: 'What comes back: PCM16 mono 24 kHz, base64, in `response.audio.delta`.'
                  client_secret:
                    type: object
                    properties:
                      value:
                        type: string
                        description: '`rts_...`, valid once.'
                      expires_at:
                        type: integer
                        description: Unix timestamp, 60 seconds after creation.
                    required:
                    - value
                    - expires_at
                    description: The one-time ticket.
                  url:
                    type: string
                    description: The WebSocket URL with the ticket, ready to open.
                required:
                - id
                - object
                - model
                - voice
                - turn_detection
                - max_seconds
                - input_audio
                - output_audio
                - client_secret
                - url
              example:
                id: rt_5c2e8a1f9d3b7e4a
                object: realtime.session
                model: spicy-live-1
                voice: Serena
                turn_detection:
                  type: server_vad
                  silence_duration_ms: 600
                max_seconds: 780
                input_audio: pcm16 mono 16 kHz, base64 in input_audio_buffer.append
                output_audio: pcm16 mono 24 kHz, base64 in response.audio.delta
                client_secret:
                  value: rts_9f1b3d5e7a2c4e6f8a0b
                  expires_at: 1758553260
                url: wss://api.spicyapi.com/v1/realtime?session=rts_9f1b3d5e7a2c4e6f8a0b
        '400':
          description: 'Invalid parameters. Body: {error: {message, type: ''invalid_request_error''}}.'
        '401':
          description: Missing or invalid API key.
        '402':
          description: Insufficient balance. Top up in the dashboard or through the get_topup_link tool; nothing was charged.
        '422':
          description: Prompt blocked by moderation (acceptable use policy). Never charged.
        '429':
          description: Rate limited or model at capacity; retry after the Retry-After header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  description: '`spicy-live-1` (the default) or `spicy-live-2` (highest quality).'
                voice:
                  type: string
                  description: 'The voice that answers (case-insensitive), default `Tina`: `Tina`, `Cindy`, `Liora Mira`, `Serena`, `Maia`, `Mia`, `Katerina`, `Jennifer`, `Sonrisa`, `Hana`, `Griet`, `Sigga`, `Bea`, `Chloe`, `Kiki`, `Sohee`, `Zane`, `Ryan`, `Raymond`, `Theo Calm`, `Aiden`, `Andre`, `Dolce`, `Bodega`, `Jakub`, `Alek`, `Emilien`, `Evan`.'
                instructions:
                  type: string
                  description: The persona and how to behave on the call, up to 8,000 characters. Defaults to a flirty, sexually open adult companion who leans into explicit talk when the caller wants it, takes the lead now and then, and keeps replies short.
                language:
                  type: string
                  description: '`spicy-live-2` only: the language of the call, a two-letter code (`en`, `zh`, `de`, `it`, `pt`, `es`, `ja`, `ko`, `fr`, `ru`). Defaults to English. A 400 on `spicy-live-1`, which detects the language itself.'
                turn_detection:
                  anyOf:
                  - type: object
                  - type: 'null'
                  description: '`spicy-live-1` only (a 400 on `spicy-live-2`, which takes turns by itself). When the persona replies. Default `{ "type": "server_vad" }`: it answers when the caller stops talking. `semantic_vad` waits for a finished thought. Optional `threshold` (-1 to 1) and `silence_duration_ms` (200 to 6000). `null` is push-to-talk: send `input_audio_buffer.commit` and `response.create` yourself.'
                user:
                  type: string
                  description: 'Your own id for the end user making this request (up to 128 characters; send an opaque id, not an email). Send it if your product serves many people: declined-prompt history, strikes and suspensions are then kept per end user, so one person''s behaviour never affects another''s requests or your account. After 10 severe violations that user gets `403 end_user_suspended`; the id is echoed back as `user` in every screening error so you can act on it. It is stored with the requests it was sent on, so `DELETE /v1/end-users/{user}` can erase that person''s data.'
              required: []
  /v1/realtime:
    get:
      operationId: realtimeWebsocket
      summary: Live Call WebSocket
      description: 'The call itself: a WebSocket (wss://) opened with the session ticket. Send microphone audio, receive the persona''s voice and transcripts as JSON events. Open `wss://api.spicyapi.com/v1/realtime?session=`, the `url` from `POST /v1/realtime/sessions`, within 60 seconds of creating it. No `Authorization` header: the ticket is the credential, so a browser can connect directly. An unknown, used or expired ticket is a 401 before the upgrade. Events follow the OpenAI Realtime API shape. Send JSON text frames (up to 256 KB). Accepted client events: `input_audio_buffer.append` (`audio`: base64 PCM16 mono 16 kHz, about 100 ms per chunk), `input_audio_buffer.commit`, `input_audio_buffer.clear`, `response.create`, `response.cancel`, `conversation.item.create` (a user message with `input_text` parts only, screened before it is sent), and `session.update` with only `session.turn_detection`. Persona and voice are fixed by the session. Anything else returns an `error` event. On `spicy-live-2` turn-taking is automatic: `input_audio_buffer.commit`, `.clear`, `response.create` and `response.cancel` are accepted and ignored, and `session.update` returns `unsupported_field`. Server events: `session.created`, `session.updated`, `input_audio_buffer.speech_started`, `input_audio_buffer.speech_stopped`, `input_audio_buffer.committed`, `conversation.item.input_audio_transcription.delta` and `.completed` (what the caller said), `response.created`, `response.audio.delta` (`delta`: base64 PCM16 mono 24 kHz), `response.audio_transcript.delta` and `.done` (what the persona said), `response.done` and `error`. SpicyAPI adds `spicy.usage` (`{ turn, cost_usd, total_cost_usd }`) after each billed turn and `spicy.session_expired` when the call reaches its time limit, after which the socket closes. Error events carry `error.code`: `payment_required` (balance or spend limit reached; the call ends), `content_blocked` (a transcript failed screening; the call ends), `moderation_unavailable` (screening unreachable; the call ends, retry shortly), `upstream_unavailable` (the voice service failed), `unsupported_event`, `unsupported_item`, `unsupported_field`, `invalid_json` and `invalid_event` (the call continues).'
      tags:
      - Live calls
      security: []
      responses:
        '101':
          description: The socket, carrying JSON events in both directions. The first server event is `session.created`.
        '401':
          description: Unknown, used or expired session ticket.
      x-websocket:
        url: wss://api.spicyapi.com/v1/realtime?session={ticket}
        protocol: OpenAI Realtime event shape, JSON text frames
      parameters:
      - name: session
        in: query
        required: true
        description: The ticket, `client_secret.value` from `POST /v1/realtime/sessions`.
        schema:
          type: string
          description: The ticket, `client_secret.value` from `POST /v1/realtime/sessions`.
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk-spicy-...
      description: Per-account API key from https://www.spicyapi.com/dashboard/api-keys (shown once, stored hashed). Sandbox keys bill nothing.
x-openai-compatible:
  baseUrl: https://api.spicyapi.com/v1
  compatible:
  - /v1/chat/completions
  - /v1/images/generations
  - /v1/models
  - /v1/embeddings
  - /v1/audio/transcriptions
  notes: Image sizes use width*height (1024*1024). Speech returns JSON with a url unless stream is true. Live calls follow the OpenAI Realtime event shape over wss://api.spicyapi.com/v1/realtime after POST /v1/realtime/sessions. Edits and video are Spicy API specific.
x-mcp:
  endpoint: https://www.spicyapi.com/api/mcp
  transport: streamable-http
  auth: 'Authorization: Bearer sk-spicy-...'
  docs: https://www.spicyapi.com/docs
  llms: https://www.spicyapi.com/llms.txt
  skills: https://www.spicyapi.com/skills/index.json