realitydefender-sdk-go

README

Reality Defender Go SDK

Go client library for the Reality Defender API for deepfake detection and media manipulation analysis.

Installation

go get github.com/Reality-Defender/realitydefender-sdk-go

Basic Example

package main

import (
	"context"
	"fmt"
	"os"
	"time"
	"github.com/Reality-Defender/realitydefender-sdk-go/realitydefender"
)

func main() {
	// Initialize the SDK with your API key
	client, err := realitydefender.New(realitydefender.Config{
		APIKey: os.Getenv("REALITY_DEFENDER_API_KEY"),
	})
	if err != nil {
		fmt.Printf("Failed to initialize client: %v\n", err)
		os.Exit(1)
	}

	// Create a context with timeout
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancel()

	// Upload a file for analysis
	filePath := "./image.jpg"
	uploadResult, err := client.Upload(ctx, realitydefender.UploadOptions{
		FilePath: filePath,
	})
	if err != nil {
		fmt.Printf("Upload failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("Upload successful! Request ID: %s\n", uploadResult.RequestID)

	// Get the result
	result, err := client.GetResult(ctx, uploadResult.RequestID, nil)
	if err != nil {
		fmt.Printf("Failed to get result: %v\n", err)
		os.Exit(1)
	}

	// Print results
	fmt.Printf("Status: %s\n", result.Status)
	if result.Score != nil {
		fmt.Printf("Score: %.4f\n", *result.Score)
	}
}

Event-Based Example

package main

import (
	"context"
	"fmt"
	"os"
	"sync"
	"time"

	"github.com/Reality-Defender/realitydefender-sdk-go/realitydefender"
)

func main() {
	// Initialize the SDK
	client, err := realitydefender.New(realitydefender.Config{
		APIKey: os.Getenv("REALITY_DEFENDER_API_KEY"),
	})
	if err != nil {
		fmt.Printf("Failed to initialize client: %v\n", err)
		os.Exit(1)
	}

	// Create a context with timeout
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancel()

	// Create a WaitGroup to wait for the event to be received
	var wg sync.WaitGroup
	wg.Add(1)

	// Set up event handlers
	client.On("result", func(data interface{}) {
		result := data.(*realitydefender.DetectionResult)
		fmt.Printf("Result received: %s\n", result.Status)
		wg.Done()
	})

	client.On("error", func(data interface{}) {
		err := data.(error)
		fmt.Printf("Error received: %v\n", err)
		wg.Done()
	})

	// Upload a file for analysis
	filePath := "./image.jpg"
	uploadResult, err := client.Upload(ctx, realitydefender.UploadOptions{
		FilePath: filePath,
	})
	if err != nil {
		fmt.Printf("Upload failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("Upload successful! Request ID: %s\n", uploadResult.RequestID)

	// Start polling using the event-based approach
	err = client.PollForResults(ctx, uploadResult.RequestID, &realitydefender.PollOptions{
		PollingInterval: 2000, // 2 seconds between polls
		Timeout:         60000, // 60 second timeout
	})
	if err != nil {
		fmt.Printf("Polling failed: %v\n", err)
		os.Exit(1)
	}

	// Wait for the result event
	wg.Wait()
}

API Reference

Client Initialization

client, err := realitydefender.New(realitydefender.Config{
    APIKey: "your-api-key",
    // BaseURL is optional; omit it to use production (https://api.prd.realitydefender.xyz).
})

Upload a File

uploadResult, err := client.Upload(ctx, realitydefender.UploadOptions{
    FilePath: "./path/to/file.jpg",
})

Get Result

result, err := client.GetResult(ctx, uploadResult.RequestID, &realitydefender.GetResultOptions{
    MaxAttempts: 30,          // Optional, defaults to 30
    PollingInterval: 2000,    // Optional, defaults to 2000ms
})

DetectionResult includes heatmaps for IMAGE media when a non-ensemble model returns an artificial result (API status FAKE / UI ARTIFICIAL). Pre-signed URLs expire after 15 minutes; otherwise nil:

// IMAGE heatmaps: model slug → pre-signed PNG URL
fmt.Println(result.Heatmaps)

User feedback

comment := "Optional note"
fb, err := client.CreateUserFeedback(ctx, realitydefender.CreateUserFeedbackOptions{
    RequestID:        uploadResult.RequestID,
    Label:            "REAL",
    FeedbackCategory: "CONFIRMATION",
    Comment:          &comment,
})

Returns (*UserFeedback, error). UserFeedback is:

type UserFeedback struct {
    ID             string `json:"id,omitempty"`             // Created feedback record id
    UserID         string `json:"userId,omitempty"`         // Authenticated user id
    RequestID      string `json:"requestId,omitempty"`       // Media / detection request id
    InstitutionID  string `json:"institutionId,omitempty"`  // Organization id
    Text           string `json:"text,omitempty"`           // Comment body if sent in request
    Category       string `json:"category,omitempty"`       // Stored feedbackCategory
    UserName       string `json:"userName,omitempty"`       // Display name when present
    UserEmail      string `json:"userEmail,omitempty"`       // Email when present
    OrgName        string `json:"orgName,omitempty"`         // Organization name when present
    MediaType      string `json:"mediaType,omitempty"`       // e.g. VIDEO, IMAGE when present
    MediaViewURL   string `json:"mediaViewUrl,omitempty"`    // Link to result in web app when present
    MediaSource    string `json:"mediaSource,omitempty"`     // e.g. file upload or API source label
    Label          string `json:"label,omitempty"`           // REAL, SYNTHETIC, MANIPULATED, UNKNOWN
    CreatedAt      string `json:"createdAt,omitempty"`       // Serialized timestamp when present
}

Poll for Results (Event-Based)

// Set up event handlers
client.On("result", func(data interface{}) {
    result := data.(*realitydefender.DetectionResult)
    // Handle result
})

client.On("error", func(data interface{}) {
    err := data.(error)
    // Handle error
})

// Start polling
err = client.PollForResults(ctx, uploadResult.RequestID, &realitydefender.PollOptions{
    PollingInterval: 2000, // Optional, defaults to 2000ms
    Timeout:         60000, // Optional, defaults to 60000ms
})

Convenience Method

// Upload and get result in one step
result, err := client.DetectFile(ctx, "./path/to/file.jpg")

Development

The included Justfile has all the shortcuts needed to build the module, run tests, examples, etc.

Supported file types and size limits

There is a size limit for each of the supported file types.

File Type	Extensions	Size Limit (bytes)	Size Limit (MB)
Video	.mp4, .mov	262,144,000	250 MB
Image	.jpg, .png, .jpeg, .gif, .webp	52,428,800	50 MB
Audio	.flac, .wav, .mp3, .m4a, .aac, .alac, .ogg	20,971,520	20 MB
Text	.txt	5,242,880	5 MB

Supported social media platforms

The Reality Defender API supports analysis of media from the following social media platforms:

• Facebook
• Instagram
• Twitter
• YouTube
• TikTok