API Reference

Endpoints

All endpoints are available at your gateway URL. Authentication uses x402 payment signatures for session creation and Bearer tokens for session management.

Payment flow (x402)

1.Call POST /v1/sessions without a payment header.

2.Receive 402 with a PAYMENT-REQUIRED header containing price, wallet, and network.

3.Sign a USDC authorization (EIP-3009) with your wallet.

4.Retry the same request with the PAYMENT-SIGNATURE header.

5.Server verifies the payment and creates your session.

No accounts or API keys. Your wallet address is your identity. First 5 minutes are free per session.

GET/health

Service availability and pricing.

AuthNone

bash

curl https://render.mirrorstage.ai/health

response

{
  "status": "available",
  "available": true,
  "price_per_minute_usd": 0.10,
  "free_trial_minutes": 5,
  "min_duration_minutes": 10,
}

GET/tos

AuthNone

bash

curl https://render.mirrorstage.ai/tos

POST/v1/sessions

Create a GPU rendering session. Returns 402 with payment instructions on first call.

Authx402 (PAYMENT-SIGNATURE header)

Parameters

reference_image*fileFace image (JPEG/PNG)

output_url*stringRTMP destination URL

duration_minutesintSession length (default: 15)

accept_tos*boolMust be true

bash

# Step 1: Get payment requirements
curl -X POST https://render.mirrorstage.ai/v1/sessions \
  -F "reference_image=@face.jpg" \
  -F "output_url=rtmp://your-server/live/stream" \
  -F "accept_tos=true"
# → 402 with PAYMENT-REQUIRED header

# Step 2: Sign USDC authorization, retry with payment
curl -X POST https://render.mirrorstage.ai/v1/sessions \
  -H "PAYMENT-SIGNATURE: <signed_payment>" \
  -F "reference_image=@face.jpg" \
  -F "output_url=rtmp://your-server/live/stream" \
  -F "accept_tos=true"

response

{
  "session_id": "abc-123",
  "token": "sk_...",
  "status": "warming",
  "websocket_url": "wss://render.mirrorstage.ai/v1/sessions/abc-123/stream?token=sk_...",
  "status_url": "https://render.mirrorstage.ai/v1/sessions/abc-123",
  "estimated_ready_seconds": 300,
  "duration_minutes": 15,
  "price_usd": 1.00
}

GET/v1/sessions/:id

Poll session status. Wait for "active" before streaming audio.

AuthBearer token

bash

curl https://render.mirrorstage.ai/v1/sessions/abc-123 \
  -H "Authorization: Bearer sk_..."

response

{
  "session_id": "abc-123",
  "status": "active",
  "ready": true,
  "remaining_seconds": 900,
  "expires_at": "2025-01-01T12:15:00Z"
}

WS/v1/sessions/:id/stream

Bidirectional WebSocket for real-time audio streaming. Send PCM audio frames, receive control messages.

AuthToken as query param (?token=...)

Parameters

Binary frames*bytesPCM int16, 16kHz, mono audio

Text framesJSONControl messages (e.g. flush)

python

import websockets, struct

async with websockets.connect(
    "wss://render.mirrorstage.ai/v1/sessions/abc-123/stream?token=sk_..."
) as ws:
    # Send PCM audio (16kHz, int16, mono)
    await ws.send(audio_bytes)

    # Receive control messages
    msg = await ws.recv()  # {"type": "chunk_done"}

POST/v1/sessions/:id/extend

Add time to an active session. Requires additional payment.

AuthBearer token + x402

Parameters

duration_minutesintMinutes to add (default: 5)

bash

curl -X POST https://render.mirrorstage.ai/v1/sessions/abc-123/extend \
  -H "Authorization: Bearer sk_..." \
  -H "PAYMENT-SIGNATURE: <signed_payment>" \
  -H "Content-Type: application/json" \
  -d '{"duration_minutes": 10}'

response

{
  "session_id": "abc-123",
  "added_minutes": 10,
  "new_expires_at": "2025-01-01T12:25:00Z",
  "total_remaining_seconds": 1500,
  "price_usd": 1.00
}

DELETE/v1/sessions/:id

End a session early. Stops the GPU worker and RTMP stream.

AuthBearer token

bash

curl -X DELETE https://render.mirrorstage.ai/v1/sessions/abc-123 \
  -H "Authorization: Bearer sk_..."

response

{
  "session_id": "abc-123",
  "status": "ended",
  "gpu_seconds_used": 420
}