API documentation

Authorization: Bearer <your_api_key>

{
  "name": "Atlas API",
  "version": "8.0",
  "endpoints": {
    "POST /v1/generate": "Audio + image → lip-sync avatar video",
    "GET /v1/jobs/{id}": "Get job status and details",
    "GET /v1/jobs/{id}/result": "Get presigned download URL for completed job output",
    "GET /v1/jobs": "List your recent jobs",
    "POST /v1/realtime/session": "Create realtime avatar session",
    "POST /v1/realtime/session/{id}/viewer": "Get a view-only token for an active session",
    "PATCH /v1/realtime/session/{id}": "Hot-swap face image mid-session",
    "GET /v1/realtime/session/{id}": "Get session status",
    "DELETE /v1/realtime/session/{id}": "End session and release GPU",
    "GET /v1/health": "Health check",
    "GET /v1/status": "System status",
    "GET /v1/me": "Your API key info and usage",
    "POST /v1/organizations": "Create an organization",
    "GET /v1/organizations": "List your organizations",
    "GET /v1/organizations/{id}": "Organization details and members",
    "POST /v1/organizations/{id}/members": "Add a member",
    "DELETE /v1/organizations/{id}/members/{mid}": "Remove a member",
    "POST /v1/organizations/{id}/scim-tokens": "Generate SCIM bearer token",
    "GET /v1/organizations/{id}/sso": "Get SSO configuration",
    "POST /v1/organizations/{id}/sso/setup": "Generate WorkOS Admin Portal setup link",
    "POST /v1/organizations/{id}/sso/enable": "Enable or disable SSO",
    "GET /v1/auth/sso": "Start SSO login with org_slug",
    "GET /scim/v2/Users": "SCIM: List provisioned users",
    "POST /scim/v2/Users": "SCIM: Provision a user",
    "GET /scim/v2/Users/{id}": "SCIM: Get user",
    "PUT /scim/v2/Users/{id}": "SCIM: Replace user",
    "PATCH /scim/v2/Users/{id}": "SCIM: Update user attributes",
    "DELETE /scim/v2/Users/{id}": "SCIM: Deprovision a user",
    "GET /scim/v2/ServiceProviderConfig": "SCIM: Service provider capabilities",
    "GET /scim/v2/Schemas": "SCIM: Supported schemas",
    "GET /scim/v2/ResourceTypes": "SCIM: Resource types"
  },
  "authentication": "Authorization: Bearer <api_key>",
  "flow": {
    "offline": "POST → 202 {job_id} → poll GET /v1/jobs/{id} → GET /v1/jobs/{id}/result",
    "realtime": "POST /v1/realtime/session → connect to LiveKit with token → DELETE to end"
  }
}

{
  "job_id": "a1b2c3d4e5f6",
  "status": "pending",
  "message": "Job accepted. Poll GET /v1/jobs/a1b2c3d4e5f6 for status."
}

# Step 1, Submit job
curl -X POST "https://api.atlasv1.com/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@speech.mp3" \
  -F "image=@face.jpg"
# Returns: {"job_id": "a1b2c3d4e5f6", "status": "pending", ...}

# Step 2, Poll
curl "https://api.atlasv1.com/v1/jobs/a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Returns: {"status": "completed", ...} when done

# Step 3, Get presigned URL
curl "https://api.atlasv1.com/v1/jobs/a1b2c3d4e5f6/result" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Returns: {"url": "https://...", "content_type": "video/mp4", "expires_in": 86400}

# Download from presigned URL (no auth needed)
curl -o output.mp4 "PRESIGNED_URL_FROM_ABOVE"

{
  "jobs": [
    {
      "job_id": "a1b2c3d4e5f6",
      "type": "video",
      "status": "completed",
      "created_at": "2026-03-25T16:47:07Z",
      "completed_at": "2026-03-25T16:47:52Z",
      "output_duration": null,
      "input_chars": null,
      "error_code": null
    },
  ],
  "count": 42,
  "limit": 20,
  "offset": 0
}

{
  "job_id": "a1b2c3d4e5f6",
  "type": "video",
  "status": "processing",
  "queue_position": 0,
  "input": {
    "text_preview": null,
    "language": null,
    "chars": null,
    "audio_size": 105000,
    "image_size": 52000
  },
  "output": {
    "duration": null,
    "size_bytes": null,
    "sample_rate": null
  },
  "error": null,
  "error_code": null,
  "timing": {
    "created_at": "2026-03-25T16:47:07Z",
    "started_at": "2026-03-25T16:47:09Z",
    "completed_at": null
  }
}

{
  "job_id": "a1b2c3d4e5f6",
  "type": "video",
  "status": "completed",
  "queue_position": 0,
  "input": {
    "text_preview": null,
    "language": null,
    "chars": null,
    "audio_size": 105000,
    "image_size": 52000
  },
  "output": {
    "duration": null,
    "size_bytes": 4634000,
    "sample_rate": null,
    "has_result": true
  },
  "error": null,
  "error_code": null,
  "timing": {
    "created_at": "2026-03-25T16:47:07Z",
    "started_at": "2026-03-25T16:47:09Z",
    "completed_at": "2026-03-25T16:47:52Z"
  },
  "url": "https://t3.storage.dev/atlas-jobs/.../output.mp4?X-Amz-Algorithm=...",
  "expires_in": 86400,
  "result_url": "/v1/jobs/a1b2c3d4e5f6/result"
}

{
  "job_id": "a1b2c3d4e5f6",
  "type": "video",
  "status": "failed",
  "queue_position": 0,
  "input": {
    "text_preview": null,
    "language": null,
    "chars": null,
    "audio_size": 105000,
    "image_size": 52000
  },
  "output": {
    "duration": null,
    "size_bytes": null,
    "sample_rate": null
  },
  "error": "Processing failed. Please try again.",
  "error_code": "generation_failed",
  "timing": {
    "created_at": "2026-03-25T16:47:07Z",
    "started_at": "2026-03-25T16:47:09Z",
    "completed_at": "2026-03-25T16:47:40Z"
  }
}

{
  "url": "https://t3.storage.dev/atlas-jobs/.../output.mp4?X-Amz-Algorithm=...",
  "content_type": "video/mp4",
  "expires_in": 86400
}

{
  "authenticated": true,
  "key_prefix": "ak_...",
  "name": "My API Key",
  "tier": "starter",
  "requests_used": 14,
  "rate_limit": {
    "requests_per_minute": 30,
    "remaining": 28,
    "resets_in": "42s"
  },
  "billing": "pay_as_you_go"
}

{
  "status": "operational",
  "services": {
    "avatar_generation": "available",
    "voice_synthesis": "available"
  }
}

{
  "status": "operational"
}

{
  "session_id": "ses_x9y8z7w6v5u4...",
  "livekit_url": "wss://your-livekit-instance.livekit.cloud",
  "token": "<livekit_jwt_token>",
  "room": "atlas-rt-ses_x9y8z7w6v5u4...",
  "mode": "passthrough",
  "idle_timeout_seconds": 300,
  "pricing": "$7/hour, prorated per second"
}

{
  "session_id": "ses_a1b2c3d4e5f6...",
  "livekit_url": "wss://livekit.example.com",
  "token": "eyJ...",
  "room": "atlas-rt-ses_a1b2c3d4e5f6...",
  "viewer_id": "viewer-abc123def456",
  "role": "viewer",
  "permissions": {
    "can_publish": false,
    "can_subscribe": true,
    "can_publish_data": false
  }
}

{
  "session_id": "ses_a1b2c3d4e5f6...",
  "status": "active",
  "room": "atlas-rt-ses_a1b2c3d4e5f6...",
  "started_at": "2026-04-01T01:30:00Z",
  "ended_at": null,
  "duration_seconds": 142.5
}

{
  "session_id": "ses_a1b2c3d4e5f6...",
  "status": "ended",
  "room": "atlas-rt-ses_a1b2c3d4e5f6...",
  "started_at": "2026-04-01T01:30:00Z",
  "ended_at": "2026-04-01T01:35:22Z",
  "duration_seconds": 322.0
}

{
  "session_id": "ses_a1b2c3d4e5f6...",
  "face_updated": true,
  "metadata_pushed": true,
  "message": "Face image updated. The avatar will switch within seconds."
}

{
  "session_id": "ses_a1b2c3d4e5f6...",
  "status": "ended",
  "duration_seconds": 322.0,
  "estimated_cost": "$0.8944",
  "credits_deducted_cents": 89
}

{
  "error": "already_ended",
  "message": "Session already ended."
}

import { Room, RoomEvent } from "livekit-client";

async function startRealtimeAvatar(faceUrl?: string) {
  // Step 1, Create session via your backend (which calls Atlas API)
  const res = await fetch("/api/realtime-session", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ face_url: faceUrl }),
  });
  const { session_id, livekit_url, token, room: roomName } = await res.json();

  // Step 2, Connect to LiveKit room
  const room = new Room();

  room.on(RoomEvent.TrackSubscribed, (track) => {
    if (track.kind === "video") {
      const element = track.attach();
      document.getElementById("avatar-container")?.appendChild(element);
    }
  });

  await room.connect(livekit_url, token);
  console.log("Connected to room:", roomName);

  return { room, sessionId: session_id };
}

// Usage
const { room, sessionId } = await startRealtimeAvatar(
  "https://example.com/face.jpg"
);

// Publish your TTS / pipeline audio (see Passthrough Mode, persistent audio track)
// const audioTrack = await createLocalAudioTrack({ ... });
// await room.localParticipant.publishTrack(audioTrack);

// When done, disconnect client and end session
room.disconnect();
await fetch(`/api/realtime-session/${sessionId}`, { method: "DELETE" });

// app/api/realtime-session/route.ts
export async function POST(req: Request) {
  const { face_url } = await req.json();

  const res = await fetch("https://api.atlasv1.com/v1/realtime/session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ATLAS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ face_url, mode: "passthrough" }),
  });

  return Response.json(await res.json(), { status: res.status });
}

import { useAtlasSession } from "@northmodellabs/atlas-react";

function AvatarPage() {
  const session = useAtlasSession({
    createSession: async (face) => {
      const form = new FormData();
      if (face) form.append("face", face);
      const res = await fetch("/api/session", { method: "POST", body: form });
      return res.json(); // { sessionId, livekitUrl, token }
    },
    deleteSession: async (id) => {
      await fetch(`/api/session/${id}`, { method: "DELETE" });
    },
  });

  return (
    <div>
      <div ref={session.videoRef} style={{ width: 512, height: 512 }} />

      {session.status === "idle" && (
        <button onClick={() => session.connect(myFaceFile)}>Start</button>
      )}

      {session.status === "connected" && (
        <>
          <button onClick={() => session.setMicEnabled(session.muted)}>
            {session.muted ? "Unmute" : "Mute"}
          </button>
          <button onClick={session.disconnect}>End</button>
        </>
      )}
    </div>
  );
}

import { useEffect, useRef } from "react";
import { useAtlasSession } from "@northmodellabs/atlas-react";
import { LocalAudioTrack, Track } from "livekit-client";

const session = useAtlasSession({
  autoEnableMic: false,
  createSession: async (face) => {
    const form = new FormData();
    if (face) form.append("face", face);
    form.append("mode", "passthrough");
    const res = await fetch("/api/session", { method: "POST", body: form });
    return res.json();
  },
  deleteSession: async (id) => {
    await fetch(`/api/session/${id}`, { method: "DELETE" });
  },
});

// Refs for the persistent audio pipeline
const audioCtxRef = useRef(null);
const destRef = useRef(null);
const ttsSourceRef = useRef(null);

// Publish a persistent audio track when connected
useEffect(() => {
  if (session.status !== "connected" || !session.room) return;

  const audioCtx = new AudioContext();
  const dest = audioCtx.createMediaStreamDestination();
  const mediaTrack = dest.stream.getAudioTracks()[0];
  const lkTrack = new LocalAudioTrack(mediaTrack);

  audioCtxRef.current = audioCtx;
  destRef.current = dest;

  session.room.localParticipant.publishTrack(lkTrack, {
    name: "tts-audio",
    source: Track.Source.Unknown,
  });

  return () => {
    ttsSourceRef.current?.stop();
    session.room?.localParticipant.unpublishTrack(lkTrack);
    lkTrack.stop();
    audioCtx.close();
  };
}, [session.status, session.room]);

// Play TTS audio through the persistent track
function playTtsAudio(base64Audio) {
  const audioCtx = audioCtxRef.current;
  const dest = destRef.current;
  if (!audioCtx || !dest) return;

  ttsSourceRef.current?.stop(); // cancel previous if still playing

  const binary = atob(base64Audio);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);

  audioCtx.decodeAudioData(bytes.buffer.slice(0)).then((buf) => {
    const source = audioCtx.createBufferSource();
    source.buffer = buf;
    source.connect(dest);
    ttsSourceRef.current = source;
    source.onended = () => { source.disconnect(); ttsSourceRef.current = null; };
    source.start();
  });
}

// Use it: get LLM text first, then fetch TTS separately
async function handleUserMessage(text) {
  // Text appears instantly (no waiting for TTS)
  const chatRes = await fetch("/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  const { text: reply } = await chatRes.json();

  // TTS audio fetched in background (avatar speaks when ready)
  if (reply) {
    const ttsRes = await fetch("/api/tts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: reply }),
    });
    const { audio } = await ttsRes.json();
    if (audio) playTtsAudio(audio);
  }
}

// app/api/session/route.ts
const API_KEY = process.env.ATLAS_API_KEY;
const API_URL = process.env.ATLAS_API_URL || "https://api.atlasv1.com";

export async function POST(req: Request) {
  const contentType = req.headers.get("content-type") || "";

  // Supports both form uploads and JSON (for rendering mode)
  let body: BodyInit;
  let headers: Record<string, string> = { Authorization: `Bearer ${API_KEY}` };

  if (contentType.includes("multipart/form-data")) {
    body = await req.formData();
  } else {
    const json = await req.json();
    body = JSON.stringify(json); // { face_url, mode: "passthrough" } for rendering
    headers["Content-Type"] = "application/json";
  }

  const res = await fetch(`${API_URL}/v1/realtime/session`, {
    method: "POST",
    headers,
    body,
  });
  return Response.json(await res.json(), { status: res.status });
}

// app/api/session/[id]/route.ts
export async function DELETE(_req: Request, { params }: { params: { id: string } }) {
  const res = await fetch(`${API_URL}/v1/realtime/session/${params.id}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  return Response.json(await res.json(), { status: res.status });
}

{
  "error": "error_code",
  "message": "Human-readable description"
}

{
  "error": "unauthorized",
  "message": "Missing Authorization header. Use: Authorization: Bearer <api_key>"
}

{
  "error": "unauthorized",
  "message": "Invalid Authorization format. Use: Authorization: Bearer <api_key>"
}

{
  "error": "not_ready",
  "message": "Job is still processing. Poll GET /v1/jobs/{id} until status is completed."
}

{
  "error": "rate_limit_exceeded",
  "message": "Basic self-serve rate limit reached. Retry after the returned delay.",
  "retry_after_seconds": 12
}

{
  "error": "queue_unavailable",
  "message": "Job queue is temporarily unavailable. Please try again in a moment."
}

POST /v1/organizations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "name": "Acme AI" }

// 201 Created
{
  "id": "org_...",
  "name": "Acme AI",
  "slug": "acme-ai",
  "owner": "owner@example.com"
}

[
  {
    "id": "org_...",
    "name": "Acme AI",
    "slug": "acme-ai",
    "plan": "enterprise",
    "role": "owner"
  }
]

{
  "id": "org_...",
  "name": "Acme AI",
  "slug": "acme-ai",
  "plan": "enterprise",
  "your_role": "owner",
  "members": [
    {
      "id": "mem_...",
      "email": "owner@example.com",
      "role": "owner",
      "active": true,
      "display_name": "Owner",
      "created_at": "2026-05-21T18:00:00+00:00"
    }
  ]
}

POST /v1/organizations/org_.../members
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "email": "teammate@example.com",
  "role": "member"
}

// role: "admin", "member", or "viewer"

POST /v1/organizations/org_.../sso/setup
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "org_slug": "acme-ai",
  "return_url": "https://yourapp.com/settings/sso"
}

// 200 OK
{
  "setup_url": "https://id.workos.com/portal/...",
  "workos_org_id": "org_..."
}

GET /v1/auth/sso?org_slug=acme-ai

// 200 OK
{
  "authorization_url": "https://api.workos.com/sso/authorize?...",
  "state": "..."
}

POST /v1/organizations/org_.../scim-tokens
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "label": "Okta production" }

// 201 Created
{
  "token_id": "sctk_...",
  "token": "scim_...",
  "label": "Okta production",
  "expires_at": "2027-05-21T18:00:00+00:00",
  "warning": "Store this token securely. It will not be shown again."
}

POST /scim/v2/Users
Authorization: Bearer scim_...
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "user@example.com",
  "active": true,
  "externalId": "00u123",
  "name": {
    "givenName": "Ada",
    "familyName": "Lovelace"
  },
  "emails": [
    { "value": "user@example.com", "primary": true }
  ]
}

PATCH /scim/v2/Users/mem_...
Authorization: Bearer scim_...
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

{
  "session_id": "ses_...",
  "status": "ok"
}