Python SDK Installation Guide

pip install facesign-api

poetry add facesign-api

import os
from facesign import FaceSignClient

# Initialize with your API key from environment variable
client = FaceSignClient(
    api_key=os.getenv("FACESIGN_API_KEY"),
    server_url="https://api.facesign.ai"  # Production
    # server_url="https://api.dev.facesign.ai"  # Development
)

# Create a session with modules (legacy approach)
session_response = client.sessions.create(
    client_reference_id="user-12345",
    metadata={
        "user_id": "12345",
        "source": "python-app"
    },
    modules=[
        {"type": "identityVerification"},
        {"type": "documentAuthentication"}
    ],
    initial_phrase="Welcome! I'll help you verify your identity.",
    default_lang="en"
)

print(f"Session ID: {session_response.session.id}")
print(f"Client Secret: {session_response.client_secret.secret}")
print(f"Verification URL: {session_response.client_secret.url}")

# Create a session with flow (recommended approach)
flow_session = client.sessions.create(
    client_reference_id="user-67890",
    metadata={"source": "python-flow-app"},
    flow={
        "nodes": [
            {
                "id": "start",
                "type": "start"
            },
            {
                "id": "greeting",
                "type": "conversation",
                "prompt": "Hello! Let's verify your identity.",
                "transitions": [{"id": "t1", "condition": "true"}]
            },
            {
                "id": "face-scan", 
                "type": "face_scan",
                "mode": "capture",
                "outcomes": {
                    "captured": "end",
                    "error": "end"
                }
            },
            {
                "id": "end",
                "type": "end"
            }
        ],
        "edges": [
            {"id": "e1", "source": "start", "target": "greeting"},
            {"id": "e2", "source": "greeting", "target": "face-scan"},
            {"id": "e3", "source": "face-scan", "target": "end"}
        ]
    }
)

# Get session details
session = client.sessions.retrieve("vs_session_id_here")
print(f"Status: {session.session.status}")

if session.session.report:
    print(f"Verified: {session.session.report.is_verified}")

# List recent sessions
sessions = client.sessions.list(
    limit=10,
    status="complete",
    sort_by="createdAt",
    sort_order="desc"
)

for session in sessions.sessions:
    print(f"{session.id}: {session.status}")

import asyncio
from facesign import AsyncFaceSignClient

async def main():
    async with AsyncFaceSignClient(api_key="your_api_key") as client:
        # Create session asynchronously
        session = await client.sessions.acreate(
            client_reference_id="async-user-123",
            modules=[{"type": "identityVerification"}]
        )
        
        # List sessions asynchronously
        sessions = await client.sessions.alist(limit=5)
        
        # Get languages asynchronously
        languages = await client.languages.aget()

# Run async code
asyncio.run(main())

# Get supported languages
languages = client.languages.get()
for lang in languages.langs:
    print(f"{lang.id}: {lang.title}")

# Get available avatars
avatars = client.avatars.get()
for avatar in avatars.avatars:
    print(f"{avatar.id}: {avatar.name} ({avatar.gender})")

from facesign import (
    FaceSignAPIError, 
    AuthenticationError,
    ValidationError,
    NotFoundError
)

try:
    session = client.sessions.create(
        client_reference_id="test-user",
        modules=[{"type": "identityVerification"}]
    )
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid request data: {e}")
except NotFoundError:
    print("Resource not found")
except FaceSignAPIError as e:
    print(f"API error: {e}")

# settings.py
FACESIGN_API_KEY = "your_api_key_here"

# views.py
from django.conf import settings
from facesign import FaceSignClient

def create_verification_view(request):
    client = FaceSignClient(settings.FACESIGN_API_KEY)
    
    session = client.sessions.create(
        client_reference_id=f"user-{request.user.id}",
        metadata={"user_id": request.user.id},
        modules=[{"type": "identityVerification"}]
    )
    
    return JsonResponse({
        "session_id": session.session.id,
        "verification_url": session.client_secret.url
    })

from flask import Flask, jsonify
from facesign import FaceSignClient
import os

app = Flask(__name__)
client = FaceSignClient(os.getenv("FACESIGN_API_KEY"))

@app.route("/create-verification", methods=["POST"])
def create_verification():
    session = client.sessions.create(
        client_reference_id="user-123",
        modules=[{"type": "identityVerification"}]
    )
    
    return jsonify({
        "session_id": session.session.id,
        "verification_url": session.client_secret.url
    })

from fastapi import FastAPI
from facesign import AsyncFaceSignClient
import os

app = FastAPI()
client = AsyncFaceSignClient(os.getenv("FACESIGN_API_KEY"))

@app.post("/create-verification")
async def create_verification():
    async with client:
        session = await client.sessions.acreate(
            client_reference_id="user-123",
            modules=[{"type": "identityVerification"}]
        )
        
        return {
            "session_id": session.session.id,
            "verification_url": session.client_secret.url
        }

# Create .env file (never commit this file)
echo "FACESIGN_API_KEY=your_api_key_here" > .env

# Or export directly
export FACESIGN_API_KEY="your_api_key_here"

import os
from facesign import FaceSignClient

# This safely loads from environment variables
client = FaceSignClient(
    api_key=os.getenv("FACESIGN_API_KEY"),
    server_url=os.getenv("FACESIGN_SERVER_URL", "https://api.facesign.ai")
)

# Development environment
dev_client = FaceSignClient(
    api_key="dev_api_key",
    server_url="https://api.dev.facesign.ai"
)

# Production environment
prod_client = FaceSignClient(
    api_key="prod_api_key", 
    server_url="https://api.facesign.ai"
)