actorhub

package module
v0.1.1-0...-f4dfe84 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 18, 2026 License: MIT Imports: 10 Imported by: 0

README

ActorHub Go SDK

Official Go SDK for ActorHub.ai - Verify AI-generated content against protected identities.

Installation

go get github.com/actorhubai/actorhub-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    actorhub "github.com/actorhubai/actorhub-go"
)

func main() {
    // Initialize the client
    client := actorhub.NewClient("your-api-key")

    // Verify if an image contains protected identities
    result, err := client.Verify(context.Background(), &actorhub.VerifyRequest{
        ImageURL: "https://example.com/image.jpg",
    })
    if err != nil {
        log.Fatal(err)
    }

    if result.Protected {
        fmt.Println("Protected identity detected!")
        for _, identity := range result.Identities {
            if identity.DisplayName != nil {
                fmt.Printf("  - %s (similarity: %.2f)\n", *identity.DisplayName, *identity.SimilarityScore)
            }
        }
    }
}

Features

  • Identity Verification: Check if images contain protected identities
  • Consent Checking: Verify consent before AI generation
  • Marketplace Access: Browse and license identities
  • Automatic Retries: Built-in retry logic with exponential backoff
  • Context Support: Full context.Context support for cancellation
  • Typed Errors: Specific error types for easy handling

Usage Examples

Verify Image
// From URL
result, err := client.Verify(ctx, &actorhub.VerifyRequest{
    ImageURL: "https://example.com/image.jpg",
})

// From base64
result, err := client.Verify(ctx, &actorhub.VerifyRequest{
    ImageBase64: "base64-encoded-data...",
})

fmt.Printf("Protected: %v\n", result.Protected)
fmt.Printf("Faces detected: %d\n", result.FacesDetected)

result, err := client.CheckConsent(ctx, &actorhub.ConsentCheckRequest{
    ImageURL:    "https://example.com/face.jpg",
    Platform:    "runway",
    IntendedUse: "video",
    Region:      "US",
})

if result.Protected {
    for _, face := range result.Faces {
        fmt.Printf("Consent for video: %v\n", face.Consent.VideoGeneration)
        fmt.Printf("License available: %v\n", face.License.Available)
    }
}
Browse Marketplace
// Search listings
featured := true
listings, err := client.ListMarketplace(ctx, &actorhub.MarketplaceListRequest{
    Category: "ACTOR",
    Featured: &featured,
    SortBy:   "popular",
    Limit:    10,
})

for _, listing := range listings {
    fmt.Printf("%s - $%.2f\n", listing.Title, listing.BasePriceUSD)
}
Purchase License
purchase, err := client.PurchaseLicense(ctx, &actorhub.PurchaseLicenseRequest{
    IdentityID:         "uuid-here",
    LicenseType:        string(actorhub.LicenseTypeStandard),
    UsageType:          string(actorhub.UsageTypeCommercial),
    ProjectName:        "My AI Project",
    ProjectDescription: "Creating promotional content",
    DurationDays:       30,
})

// Redirect user to Stripe checkout
fmt.Printf("Checkout URL: %s\n", purchase.CheckoutURL)
Get My Licenses
licenses, err := client.GetMyLicenses(ctx, "active", 1, 20)

for _, license := range licenses {
    fmt.Printf("%s - %s - Expires: %v\n",
        license.IdentityName,
        license.LicenseType,
        license.ExpiresAt)
}

Error Handling

import "errors"

result, err := client.Verify(ctx, req)
if err != nil {
    var authErr *actorhub.AuthenticationError
    var rateLimitErr *actorhub.RateLimitError
    var validationErr *actorhub.ValidationError
    var notFoundErr *actorhub.NotFoundError

    switch {
    case errors.As(err, &authErr):
        fmt.Println("Invalid API key")
    case errors.As(err, &rateLimitErr):
        fmt.Printf("Rate limit exceeded. Retry after: %d seconds\n", rateLimitErr.RetryAfter)
    case errors.As(err, &validationErr):
        fmt.Printf("Validation error: %s\n", validationErr.Message)
    case errors.As(err, &notFoundErr):
        fmt.Println("Resource not found")
    default:
        fmt.Printf("Error: %v\n", err)
    }
}

Configuration

import "time"

client := actorhub.NewClient("your-api-key",
    actorhub.WithBaseURL("https://custom.actorhub.ai"),
    actorhub.WithTimeout(60 * time.Second),
    actorhub.WithMaxRetries(5),
)

API Reference

Client Methods
Method Description
Verify() Verify if image contains protected identities
GetIdentity() Get identity details by ID
CheckConsent() Check consent status for AI generation
ListMarketplace() Search marketplace listings
GetMyLicenses() Get user's purchased licenses
PurchaseLicense() Purchase a license
GetActorPack() Get Actor Pack status

Requirements

  • Go 1.21+

License

MIT License - see LICENSE for details.

Documentation

Overview

Package actorhub provides a Go client for the ActorHub.ai API.

ActorHub.ai helps protect identities from unauthorized AI-generated content. This SDK provides methods to verify images against protected identities, check consent status, browse the marketplace, and purchase licenses.

Quick Start 

client := actorhub.NewClient("your-api-key")

result, err := client.Verify(context.Background(), &actorhub.VerifyRequest{
    ImageURL: "https://example.com/image.jpg",
})
if err != nil {
    log.Fatal(err)
}

if result.Protected {
    fmt.Println("Protected identity detected!")
}

Configuration

The client can be configured with various options: 

client := actorhub.NewClient("your-api-key",
    actorhub.WithBaseURL("https://custom.actorhub.ai"),
    actorhub.WithTimeout(60 * time.Second),
    actorhub.WithMaxRetries(5),
)

Error Handling

The SDK returns typed errors for different scenarios:

  • AuthenticationError: Invalid or missing API key (401)
  • RateLimitError: Rate limit exceeded (429)
  • ValidationError: Request validation failed (422)
  • NotFoundError: Resource not found (404)
  • ServerError: Server error (5xx)

Example: 

result, err := client.Verify(ctx, req)
if err != nil {
    switch e := err.(type) {
    case *actorhub.AuthenticationError:
        fmt.Println("Invalid API key")
    case *actorhub.RateLimitError:
        fmt.Printf("Rate limit exceeded, retry after %d seconds\n", e.RetryAfter)
    default:
        fmt.Println("Error:", err)
    }
}

Package actorhub provides a Go client for the ActorHub.ai API.

Index

Constants

View Source 
const (
	// DefaultBaseURL is the default ActorHub API base URL.
	DefaultBaseURL = "https://api.actorhub.ai"

	// DefaultTimeout is the default request timeout.
	DefaultTimeout = 30 * time.Second

	// DefaultMaxRetries is the default number of retry attempts.
	DefaultMaxRetries = 3

	// Version is the SDK version.
	Version = "0.1.0"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ActorHubError 

type ActorHubError struct {
	Message      string
	StatusCode   int
	ResponseData map[string]interface{}
	RequestID    string
}

ActorHubError is the base error type for ActorHub SDK errors.

func (*ActorHubError) Error 

func (e *ActorHubError) Error() string

type ActorPackComponents 

type ActorPackComponents struct {
	Face   bool `json:"face"`
	Voice  bool `json:"voice"`
	Motion bool `json:"motion"`
}

ActorPackComponents represents Actor Pack component availability.

type ActorPackResponse 

type ActorPackResponse struct {
	ID                   string              `json:"id"`
	IdentityID           string              `json:"identity_id"`
	Name                 string              `json:"name"`
	Description          *string             `json:"description,omitempty"`
	TrainingStatus       TrainingStatus      `json:"training_status"`
	TrainingProgress     int                 `json:"training_progress"`
	TrainingImagesCount  int                 `json:"training_images_count"`
	TrainingAudioSeconds int                 `json:"training_audio_seconds"`
	Components           ActorPackComponents `json:"components"`
	LoRAModelURL         *string             `json:"lora_model_url,omitempty"`
	TotalDownloads       int                 `json:"total_downloads"`
	IsAvailable          bool                `json:"is_available"`
	TrainingError        *string             `json:"training_error,omitempty"`
	CreatedAt            *time.Time          `json:"created_at,omitempty"`
}

ActorPackResponse represents Actor Pack details.

type AuthenticationError 

type AuthenticationError struct {
	ActorHubError
}

AuthenticationError is raised when API key is invalid or missing.

func NewAuthenticationError 

func NewAuthenticationError(message string, requestID string) *AuthenticationError

NewAuthenticationError creates a new AuthenticationError.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the ActorHub API client.

func NewClient 

func NewClient(apiKey string, opts ...ClientOption) *Client

NewClient creates a new ActorHub API client.

func (*Client) CheckConsent 

func (c *Client) CheckConsent(ctx context.Context, req *ConsentCheckRequest) (*ConsentCheckResponse, error)

CheckConsent checks consent status for face before AI generation.

func (*Client) GetActorPack 

func (c *Client) GetActorPack(ctx context.Context, packID string) (*ActorPackResponse, error)

GetActorPack retrieves Actor Pack status and details.

func (*Client) GetIdentity 

func (c *Client) GetIdentity(ctx context.Context, identityID string) (*IdentityResponse, error)

GetIdentity retrieves identity details by ID.

func (*Client) GetMyLicenses 

func (c *Client) GetMyLicenses(ctx context.Context, status string, page, limit int) ([]LicenseResponse, error)

GetMyLicenses retrieves licenses purchased by the current user.

func (*Client) ListMarketplace 

func (c *Client) ListMarketplace(ctx context.Context, req *MarketplaceListRequest) ([]MarketplaceListingResponse, error)

ListMarketplace searches marketplace listings.

func (*Client) PurchaseLicense 

func (c *Client) PurchaseLicense(ctx context.Context, req *PurchaseLicenseRequest) (*PurchaseResponse, error)

PurchaseLicense purchases a license for an identity.

func (*Client) Verify 

func (c *Client) Verify(ctx context.Context, req *VerifyRequest) (*VerifyResponse, error)

Verify checks if an image contains protected identities.

type ClientOption 

type ClientOption func(*Client)

ClientOption is a function that configures the client.

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets a custom base URL.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithMaxRetries 

func WithMaxRetries(maxRetries int) ClientOption

WithMaxRetries sets the maximum number of retries.

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets a custom timeout.

type ConsentCheckRequest 

type ConsentCheckRequest struct {
	ImageURL      string    `json:"image_url,omitempty"`
	ImageBase64   string    `json:"image_base64,omitempty"`
	FaceEmbedding []float64 `json:"face_embedding,omitempty"`
	Platform      string    `json:"platform"`
	IntendedUse   string    `json:"intended_use"`
	Region        string    `json:"region,omitempty"`
}

ConsentCheckRequest represents the request for consent check.

type ConsentCheckResponse 

type ConsentCheckResponse struct {
	RequestID          string          `json:"request_id"`
	Protected          bool            `json:"protected"`
	FacesDetected      int             `json:"faces_detected"`
	Faces              []ConsentResult `json:"faces"`
	ResponseTimeMs     int             `json:"response_time_ms"`
	RateLimitRemaining *int            `json:"rate_limit_remaining,omitempty"`
}

ConsentCheckResponse is the response from consent check.

type ConsentDetails 

type ConsentDetails struct {
	CommercialUse   bool `json:"commercial_use"`
	AITraining      bool `json:"ai_training"`
	VideoGeneration bool `json:"video_generation"`
	Deepfake        bool `json:"deepfake"`
}

ConsentDetails represents consent permissions for an identity.

type ConsentLicenseInfo 

type ConsentLicenseInfo struct {
	Available bool               `json:"available"`
	URL       *string            `json:"url,omitempty"`
	Pricing   map[string]float64 `json:"pricing,omitempty"`
}

ConsentLicenseInfo represents license availability information.

type ConsentRestrictions 

type ConsentRestrictions struct {
	BlockedCategories []string `json:"blocked_categories"`
	BlockedRegions    []string `json:"blocked_regions"`
	BlockedBrands     []string `json:"blocked_brands"`
}

ConsentRestrictions represents consent restrictions.

type ConsentResult 

type ConsentResult struct {
	Protected       bool                `json:"protected"`
	IdentityID      *string             `json:"identity_id,omitempty"`
	SimilarityScore *float64            `json:"similarity_score,omitempty"`
	Consent         ConsentDetails      `json:"consent"`
	Restrictions    ConsentRestrictions `json:"restrictions"`
	License         ConsentLicenseInfo  `json:"license"`
}

ConsentResult represents an individual consent check result.

type FaceBBox 

type FaceBBox struct {
	X      float64 `json:"x"`
	Y      float64 `json:"y"`
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

FaceBBox represents face bounding box coordinates.

type IdentityResponse 

type IdentityResponse struct {
	ID                 string          `json:"id"`
	DisplayName        string          `json:"display_name"`
	ProfileImageURL    *string         `json:"profile_image_url,omitempty"`
	Status             string          `json:"status"`
	ProtectionLevel    ProtectionLevel `json:"protection_level"`
	ProtectionMode     string          `json:"protection_mode"`
	TotalVerifications int             `json:"total_verifications"`
	TotalLicenses      int             `json:"total_licenses"`
	TotalRevenue       float64         `json:"total_revenue"`
	AllowCommercial    bool            `json:"allow_commercial"`
	AllowAITraining    bool            `json:"allow_ai_training"`
	CreatedAt          *time.Time      `json:"created_at,omitempty"`
}

IdentityResponse represents identity details.

type LicenseOption 

type LicenseOption struct {
	Type           LicenseType `json:"type"`
	PriceUSD       float64     `json:"price_usd"`
	DurationDays   int         `json:"duration_days"`
	MaxImpressions *int        `json:"max_impressions,omitempty"`
}

LicenseOption represents a license option with pricing.

type LicenseResponse 

type LicenseResponse struct {
	ID                 string      `json:"id"`
	IdentityID         string      `json:"identity_id"`
	IdentityName       string      `json:"identity_name"`
	LicenseType        LicenseType `json:"license_type"`
	UsageType          UsageType   `json:"usage_type"`
	Status             string      `json:"status"`
	ProjectName        string      `json:"project_name"`
	ProjectDescription *string     `json:"project_description,omitempty"`
	AllowedPlatforms   []string    `json:"allowed_platforms"`
	MaxImpressions     *int        `json:"max_impressions,omitempty"`
	MaxOutputs         *int        `json:"max_outputs,omitempty"`
	PriceUSD           float64     `json:"price_usd"`
	StartsAt           *time.Time  `json:"starts_at,omitempty"`
	ExpiresAt          *time.Time  `json:"expires_at,omitempty"`
	CreatedAt          *time.Time  `json:"created_at,omitempty"`
}

LicenseResponse represents license details.

type LicenseType 

type LicenseType string

LicenseType represents the type of license. 

const (
	LicenseTypeStandard  LicenseType = "standard"
	LicenseTypeExtended  LicenseType = "extended"
	LicenseTypeExclusive LicenseType = "exclusive"
)

type MarketplaceListRequest 

type MarketplaceListRequest struct {
	Query    string   `json:"query,omitempty"`
	Category string   `json:"category,omitempty"`
	Tags     []string `json:"tags,omitempty"`
	Featured *bool    `json:"featured,omitempty"`
	MinPrice *float64 `json:"min_price,omitempty"`
	MaxPrice *float64 `json:"max_price,omitempty"`
	SortBy   string   `json:"sort_by,omitempty"`
	Page     int      `json:"page,omitempty"`
	Limit    int      `json:"limit,omitempty"`
}

MarketplaceListRequest represents the request for marketplace listing.

type MarketplaceListingResponse 

type MarketplaceListingResponse struct {
	ID              string     `json:"id"`
	IdentityID      string     `json:"identity_id"`
	Title           string     `json:"title"`
	Description     *string    `json:"description,omitempty"`
	Category        string     `json:"category"`
	Tags            []string   `json:"tags"`
	BasePriceUSD    float64    `json:"base_price_usd"`
	DisplayName     string     `json:"display_name"`
	ProfileImageURL *string    `json:"profile_image_url,omitempty"`
	Featured        bool       `json:"featured"`
	ViewCount       int        `json:"view_count"`
	LicenseCount    int        `json:"license_count"`
	Rating          *float64   `json:"rating,omitempty"`
	CreatedAt       *time.Time `json:"created_at,omitempty"`
}

MarketplaceListingResponse represents marketplace listing details.

type NotFoundError 

type NotFoundError struct {
	ActorHubError
}

NotFoundError is raised when requested resource is not found.

func NewNotFoundError 

func NewNotFoundError(message string, requestID string) *NotFoundError

NewNotFoundError creates a new NotFoundError.

type ProtectionLevel 

type ProtectionLevel string

ProtectionLevel represents the identity protection tier. 

const (
	ProtectionLevelFree       ProtectionLevel = "free"
	ProtectionLevelPro        ProtectionLevel = "pro"
	ProtectionLevelEnterprise ProtectionLevel = "enterprise"
)

type PurchaseLicenseRequest 

type PurchaseLicenseRequest struct {
	IdentityID         string   `json:"identity_id"`
	LicenseType        string   `json:"license_type"`
	UsageType          string   `json:"usage_type"`
	ProjectName        string   `json:"project_name"`
	ProjectDescription string   `json:"project_description"`
	DurationDays       int      `json:"duration_days,omitempty"`
	AllowedPlatforms   []string `json:"allowed_platforms,omitempty"`
	MaxImpressions     *int     `json:"max_impressions,omitempty"`
	MaxOutputs         *int     `json:"max_outputs,omitempty"`
}

PurchaseLicenseRequest represents the request for license purchase.

type PurchaseResponse 

type PurchaseResponse struct {
	CheckoutURL    string                 `json:"checkout_url"`
	SessionID      string                 `json:"session_id"`
	PriceUSD       float64                `json:"price_usd"`
	LicenseDetails map[string]interface{} `json:"license_details"`
}

PurchaseResponse is the license purchase response.

type RateLimitError 

type RateLimitError struct {
	ActorHubError
	RetryAfter int
}

RateLimitError is raised when rate limit is exceeded.

func NewRateLimitError 

func NewRateLimitError(message string, retryAfter int, requestID string) *RateLimitError

NewRateLimitError creates a new RateLimitError.

type ServerError 

type ServerError struct {
	ActorHubError
}

ServerError is raised when server returns 5xx error.

func NewServerError 

func NewServerError(message string, statusCode int, requestID string) *ServerError

NewServerError creates a new ServerError.

type TrainingStatus 

type TrainingStatus string

TrainingStatus represents the status of an Actor Pack training job. 

const (
	TrainingStatusQueued     TrainingStatus = "QUEUED"
	TrainingStatusProcessing TrainingStatus = "PROCESSING"
	TrainingStatusCompleted  TrainingStatus = "COMPLETED"
	TrainingStatusFailed     TrainingStatus = "FAILED"
)

type UsageType 

type UsageType string

UsageType represents the usage category for licensing. 

const (
	UsageTypePersonal    UsageType = "personal"
	UsageTypeEditorial   UsageType = "editorial"
	UsageTypeCommercial  UsageType = "commercial"
	UsageTypeEducational UsageType = "educational"
)

type ValidationError 

type ValidationError struct {
	ActorHubError
	Errors map[string]interface{}
}

ValidationError is raised when request validation fails.

func NewValidationError 

func NewValidationError(message string, errors map[string]interface{}, requestID string) *ValidationError

NewValidationError creates a new ValidationError.

type VerifyRequest 

type VerifyRequest struct {
	ImageURL              string `json:"image_url,omitempty"`
	ImageBase64           string `json:"image_base64,omitempty"`
	IncludeLicenseOptions bool   `json:"include_license_options,omitempty"`
}

VerifyRequest represents the request for identity verification.

type VerifyResponse 

type VerifyResponse struct {
	Protected      bool           `json:"protected"`
	FacesDetected  int            `json:"faces_detected"`
	Identities     []VerifyResult `json:"identities"`
	ResponseTimeMs int            `json:"response_time_ms"`
	RequestID      string         `json:"request_id"`
}

VerifyResponse is the response from identity verification.

type VerifyResult 

type VerifyResult struct {
	Protected         bool            `json:"protected"`
	IdentityID        *string         `json:"identity_id,omitempty"`
	SimilarityScore   *float64        `json:"similarity_score,omitempty"`
	DisplayName       *string         `json:"display_name,omitempty"`
	LicenseRequired   bool            `json:"license_required"`
	BlockedCategories []string        `json:"blocked_categories"`
	LicenseOptions    []LicenseOption `json:"license_options"`
	FaceBBox          *FaceBBox       `json:"face_bbox,omitempty"`
}

VerifyResult represents an individual identity verification result.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
Example usage of the ActorHub Go SDK.
 Example usage of the ActorHub Go SDK.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.