HTTP Signaling

GET /v1/realtime/sessions/{id}/events?event_token=EVT_TOKEN

{
  "type": "https://api.decart.ai/errors/invalid-sdp",
  "title": "Invalid SDP offer",
  "detail": "Missing ice-ufrag attribute in the SDP offer",
  "status": 400
}

// Next.js / Express — all routes are stateless pass-through
app.all("/v1/realtime/*", async (req, res) => {
  const decartUrl = `https://api.decart.ai${req.path}${req.url.includes("?") ? req.url.substring(req.url.indexOf("?")) : ""}`;

  // Build headers — inject API key, forward If-Match for ICE operations
  const headers: Record<string, string> = {
    "x-api-key": process.env.DECART_API_KEY!,
  };
  if (req.headers["content-type"]) {
    headers["Content-Type"] = req.headers["content-type"] as string;
  }
  if (req.headers["if-match"]) {
    headers["If-Match"] = req.headers["if-match"] as string;
  }
  const response = await fetch(decartUrl, {
    method: req.method,
    headers,
    body: ["GET", "DELETE"].includes(req.method)
      ? undefined
      : JSON.stringify(req.body),
  });
  // Forward response headers
  for (const header of ["location", "etag"]) {
    const value = response.headers.get(header);
    if (value) res.setHeader(header, value);
  }

  // SSE — pipe the stream directly to the client
  if (req.path.endsWith("/events")) {
    res.status(response.status);
    res.setHeader("Content-Type", "text/event-stream");
    res.setHeader("Cache-Control", "no-cache");
    res.setHeader("Connection", "keep-alive");
    response.body?.pipeTo(
      new WritableStream({
        write(chunk) { res.write(chunk); },
        close() { res.end(); },
      })
    );
    return;
  }
  if (response.status === 204) {
    return res.status(204).end();
  }
  const data = await response.json();
  res.status(response.status).json(data);
});

const pc = new RTCPeerConnection({
  iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
});

pc.ontrack = (event) => {
  document.getElementById("remote-video").srcObject = event.streams[0];
};

const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 1280, height: 720, frameRate: 20 },
  audio: true,
});
stream.getTracks().forEach((track) => pc.addTrack(track, stream));

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

// Create session — SDP exchange + ICE servers in one round-trip
const BASE = "https://api.yourplatform.com/v1/realtime";
const createRes = await fetch(`${BASE}/sessions`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "lucy_2_rt",
    sdp: { type: "offer", sdp: offer.sdp },
    prompt: "Anime style",
    enhance_prompt: true,
  }),
});

const session = await createRes.json();
const sessionId = session.session_id;
let etag = createRes.headers.get("ETag");

await pc.setRemoteDescription(session.sdp);
pc.setConfiguration({ iceServers: session.ice_servers });

// Queue candidates and flush serially to maintain ETag ordering
const candidateQueue = [];
let flushing = false;

async function flushCandidates() {
  if (flushing || candidateQueue.length === 0) return;
  flushing = true;
  const batch = candidateQueue.splice(0);
  const res = await fetch(`${BASE}/sessions/${sessionId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json", "If-Match": etag },
    body: JSON.stringify({ candidates: batch }),
  });
  etag = res.headers.get("ETag") || etag;
  flushing = false;
  if (candidateQueue.length > 0) flushCandidates();
}

pc.onicecandidate = ({ candidate }) => {
  candidateQueue.push(candidate ? candidate.toJSON() : null);
  flushCandidates();
};

// SSE for server-initiated events
const sse = new EventSource(
  `${BASE}/sessions/${sessionId}/events?event_token=${encodeURIComponent(session.events.event_token)}`
);

sse.addEventListener("ice-candidate", async (e) => {
  const data = JSON.parse(e.data);
  await pc.addIceCandidate(data.candidate === null ? null : data);
});

sse.addEventListener("ice-restart", async (e) => {
  const { ice_servers } = JSON.parse(e.data);
  pc.setConfiguration({ iceServers: ice_servers });
  const restartOffer = await pc.createOffer({ iceRestart: true });
  await pc.setLocalDescription(restartOffer);
  // If-Match: "*" bypasses ETag sequencing during restarts
  const res = await fetch(`${BASE}/sessions/${sessionId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json", "If-Match": "*" },
    body: JSON.stringify({ sdp: { type: "offer", sdp: restartOffer.sdp } }),
  });
  etag = res.headers.get("ETag") || etag;
  await pc.setRemoteDescription((await res.json()).sdp);
});

sse.addEventListener("generation_started", () => {
  document.getElementById("status").textContent = "● Live";
});

sse.addEventListener("generation_tick", (e) => {
  document.getElementById("usage").textContent = `${JSON.parse(e.data).seconds}s`;
});

sse.addEventListener("generation_ended", () => {
  document.getElementById("status").textContent = "Ended";
  sse.close();
});

// Session controls
window.setPrompt = (text) =>
  fetch(`${BASE}/sessions/${sessionId}/prompt`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt: text }),
  });

window.disconnect = async () => {
  await fetch(`${BASE}/sessions/${sessionId}`, { method: "DELETE" });
  stream.getTracks().forEach((t) => t.stop());
  sse.close();
  pc.close();
};