Ruby Quick Start Guide

Get started with FacePing's face recognition API using Ruby

Prerequisites

Installation

First, create a new project and install required gems:

mkdir faceping-ruby
cd faceping-ruby
bundle init
echo 'gem "rest-client"' >> Gemfile
bundle install

Create .env file:

FACEPING_API_KEY=your_api_key_here

Step 1: Create Face Group

Create a new file create_group.rb:

require 'rest-client'
require 'json'
require 'dotenv'

Dotenv.load

def create_group(group_name)
  begin
    response = RestClient.post(
      "https://api.faceping.ai/groups/#{group_name}",
      nil,
      { Authorization: "Bearer #{ENV['FACEPING_API_KEY']}" }
    )
    puts "Group created successfully"
    JSON.parse(response.body)
  rescue RestClient::ExceptionWithResponse => e
    puts "Error creating group: #{e.message}"
    nil
  end
end

# Usage
result = create_group('my-group')
puts result

Step 2: Upload Face Image

Create a new file upload_face.rb:

require 'rest-client'
require 'json'
require 'dotenv'

Dotenv.load

def upload_face(group_name, image_path)
  unless File.exist?(image_path)
    puts "Error: Image file not found"
    return nil
  end

  begin
    response = RestClient.post(
      "https://api.faceping.ai/groups/#{group_name}/faces",
      { image: File.new(image_path, 'rb') },
      { Authorization: "Bearer #{ENV['FACEPING_API_KEY']}" }
    )
    puts "Face uploaded successfully"
    JSON.parse(response.body)
  rescue RestClient::ExceptionWithResponse => e
    puts "Error uploading face: #{e.message}"
    nil
  end
end

# Usage
result = upload_face('my-group', 'path/to/face.jpg')
puts result

Step 3: Search for Faces

Create a new file search_faces.rb:

require 'rest-client'
require 'json'
require 'dotenv'

Dotenv.load

def search_faces(group_name, image_path)
  unless File.exist?(image_path)
    puts "Error: Image file not found"
    return []
  end

  begin
    response = RestClient.post(
      "https://api.faceping.ai/groups/#{group_name}/search",
      { image: File.new(image_path, 'rb') },
      { Authorization: "Bearer #{ENV['FACEPING_API_KEY']}" }
    )
    result = JSON.parse(response.body)
    matches = result['matches'] || []
    puts "Found #{matches.length} matches"
    matches
  rescue RestClient::ExceptionWithResponse => e
    puts "Error searching faces: #{e.message}"
    []
  end
end

# Usage
matches = search_faces('my-group', 'path/to/search-face.jpg')
matches.each do |match|
  puts "Match Score: #{match['score']}"
end

Security Notes

Images are immediately discarded after vector conversion
Face vectors cannot be reverse-engineered into images
Always use HTTPS for all API calls
Store your API keys in environment variables (.env file)