Getting started overview

Integrating with the SkyBiometry API involves a sequence of steps designed to enable developers to quickly utilize its facial recognition and analysis capabilities. The process typically begins with account creation, followed by the generation of API credentials. These credentials are then used to authenticate requests to the API's various endpoints, allowing for operations such as face detection, recognition, and emotion analysis. SkyBiometry provides a comprehensive documentation portal that details the API's structure and available methods. Developers can choose to interact with the API directly via HTTP requests or leverage one of the officially supported SDKs for languages such as Python, Java, PHP, Ruby, and .NET, which abstract much of the HTTP request logic.

Before making a live request, it is recommended to review the SkyBiometry pricing page to understand the available tiers, including the free tier which offers 1,000 detections per month. This allows for initial development and testing without immediate cost. The API itself follows a RESTful architecture, which typically means resources are manipulated using standard HTTP methods like GET, POST, PUT, and DELETE, and responses are commonly formatted in JSON, a standard data interchange format documented by json.org.

The following table summarizes the key steps to begin using the SkyBiometry API:

Step What to do Where
1. Sign Up Create a SkyBiometry account. SkyBiometry Sign Up Page
2. Get API Keys Obtain your unique API Key and API Secret. SkyBiometry Account Dashboard - API Keys
3. Review Documentation Understand API endpoints, parameters, and authentication. SkyBiometry Documentation
4. Make First Request Send an authenticated request to a core endpoint (e.g., face detection). Your preferred development environment (e.g., cURL, Postman, SDK)
5. Handle Response Parse the API response and integrate data. Your application logic

Create an account and get keys

To access the SkyBiometry API, you must first create an account. This process establishes your user profile and provides access to the SkyBiometry dashboard, where you can manage your API usage and retrieve credentials. Navigate to the SkyBiometry sign-up page and complete the registration form. You will typically be asked for an email address and a password. After successful registration, an account verification step, often via email, may be required to activate your account fully.

Once your account is active and you have logged into the SkyBiometry dashboard, locate the section related to API keys or credentials. This is usually found under a 'Settings', 'Developer', or 'API Access' menu item. On the SkyBiometry API Keys page, you will find your unique API Key and API Secret. These two pieces of information are crucial for authenticating your requests to the SkyBiometry API. The API Key identifies your application, while the API Secret is used to sign your requests, ensuring their integrity and proving your identity to the service. It is critical to keep your API Secret confidential and secure, as unauthorized access could lead to misuse of your account and its associated quotas.

For security best practices, avoid embedding API keys directly into client-side code or public repositories. Instead, manage them as environment variables or through a secure backend service. The SkyBiometry API uses a form of OAuth 2.0 for authentication, specifically requiring the API Key and Secret to generate a valid signature for each request. Details on how to construct this signature are available in the SkyBiometry API reference documentation on authentication.

Your first request

After obtaining your API Key and Secret, you can make your first API request. This example will demonstrate a basic face detection call using cURL, a common command-line tool for making HTTP requests. The goal is to send an image URL to the SkyBiometry API and receive a JSON response containing detected faces, their coordinates, and potentially other attributes like age or gender, depending on the request parameters.

Before executing the command, ensure you have an image URL accessible on the internet. For this example, we'll use the /faces/detect endpoint, which is one of the most fundamental operations in the SkyBiometry API. The request will include your API Key, API Secret, and the URL of the image you want to analyze.

Here's a template for a cURL command. Replace YOUR_API_KEY, YOUR_API_SECRET, and YOUR_IMAGE_URL with your actual credentials and an image URL.

curl -X POST \
  'https://api.skybiometry.com/fc/faces/detect' \
  -F 'api_key=YOUR_API_KEY' \
  -F 'api_secret=YOUR_API_SECRET' \
  -F 'urls=YOUR_IMAGE_URL' \
  -F 'attributes=all'

In this command:

  • -X POST specifies the HTTP POST method.
  • 'https://api.skybiometry.com/fc/faces/detect' is the API endpoint for face detection.
  • -F 'api_key=YOUR_API_KEY' passes your API Key as a form field.
  • -F 'api_secret=YOUR_API_SECRET' passes your API Secret as a form field.
  • -F 'urls=YOUR_IMAGE_URL' provides the URL of the image to be processed. You can specify multiple URLs separated by commas.
  • -F 'attributes=all' requests all available attributes for detected faces, such as age, gender, and emotion. You can customize this to request specific attributes if needed, as detailed in the SkyBiometry /faces/detect API reference.

Upon successful execution, the API will return a JSON response similar to this (simplified for brevity):

{
  "photos": [
    {
      "url": "YOUR_IMAGE_URL",
      "tags": [
        {
          "tid": "FACE_ID_STRING",
          "confidence": 98,
          "center": {"x": 50, "y": 50},
          "width": 20,
          "height": 20,
          "attributes": {
            "age_est": {"value": 30},
            "gender": {"value": "male"},
            "emotion": {"value": "neutral"}
          }
        }
      ]
    }
  ]
}

This response indicates that a face was detected, providing its unique tag ID (tid), confidence level, position (center, width, height), and estimated attributes. If no faces are detected, the tags array will be empty. Review the SkyBiometry /faces/detect documentation for a complete list of possible response fields and their meanings.

Common next steps

After successfully making your first API call, several common next steps can help you further integrate SkyBiometry into your application:

  1. Explore Other Endpoints: The /faces/detect endpoint is foundational, but SkyBiometry offers other functionalities such as face recognition (comparing faces against a known set), face training (teaching the system to recognize specific individuals), and various face attribute analyses. Experiment with these to see how they fit your application's requirements.
  2. Integrate with an SDK: While cURL is useful for quick testing, using one of the official SkyBiometry SDKs for Python, Java, PHP, Ruby, or .NET can simplify integration significantly. SDKs handle authentication, request formatting, and response parsing, allowing you to focus on your application logic.
  3. Error Handling: Implement robust error handling in your application. The API will return specific HTTP status codes and JSON error messages for issues such as invalid credentials, rate limit breaches, or malformed requests. Understanding these SkyBiometry error codes is essential for building a resilient integration.
  4. Manage Rate Limits: Be aware of the API rate limits associated with your account tier. Implement strategies like exponential backoff for retries to avoid exceeding these limits, especially in production environments.
  5. Secure Your API Keys: Reiterate the importance of keeping your API Secret secure. For server-side applications, store keys as environment variables. For client-side applications requiring direct API access, consider using a proxy server to hide your secret, or explore alternative authentication methods if available.
  6. Monitor Usage: Regularly check your API usage through the SkyBiometry account dashboard to stay within your chosen plan's limits and anticipate scaling needs.
  7. Explore Webhooks (if applicable): Some APIs offer webhooks for asynchronous notifications. While the SkyBiometry documentation primarily focuses on synchronous requests, understanding webhooks as a concept is valuable for future API integrations.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here's a guide to troubleshooting some frequent problems:

  • Invalid API Key or Secret:
    • Symptom: An error message indicating invalid credentials, unauthorized access, or a 401 HTTP status code.
    • Solution: Double-check that you have copied your API Key and API Secret precisely from your SkyBiometry account dashboard. Ensure there are no leading or trailing spaces. The API Secret is case-sensitive.
  • Incorrect Endpoint URL:
    • Symptom: A 404 HTTP status code (Not Found) or a connection error.
    • Solution: Verify that the base URL and endpoint path are correct, matching the SkyBiometry API reference. For example, ensure you are using https://api.skybiometry.com/fc/faces/detect for face detection.
  • Malformed Request Body or Parameters:
    • Symptom: A 400 HTTP status code (Bad Request) with an error message detailing missing or incorrect parameters.
    • Solution: Review the /faces/detect endpoint documentation carefully. Ensure all required parameters (like api_key, api_secret, urls) are present and correctly formatted. Check for proper URL encoding if passing parameters in the URL query string, although SkyBiometry's -F flag in cURL handles this for form data.
  • Image URL Accessibility Issues:
    • Symptom: The API responds with an error indicating it could not fetch or process the image, even if your credentials are correct.
    • Solution: Ensure the YOUR_IMAGE_URL is publicly accessible and directly linkable. Test the URL in a browser or with curl YOUR_IMAGE_URL to confirm it returns an image directly. SkyBiometry's servers must be able to reach and download the image. Images behind authentication, on local networks, or requiring JavaScript to load will not work.
  • Rate Limit Exceeded:
    • Symptom: A 429 HTTP status code (Too Many Requests) or an error message indicating rate limiting.
    • Solution: Your account has a limit on the number of requests you can make within a certain timeframe. Wait for the rate limit to reset, or consider upgrading your SkyBiometry plan if you consistently hit this limit. Implement retry logic with exponential backoff in your application.
  • Network or SSL/TLS Issues:
    • Symptom: Connection failures or SSL certificate errors.
    • Solution: Ensure your network allows outbound connections to api.skybiometry.com on port 443 (HTTPS). If using cURL, ensure your environment's SSL certificates are up to date.

For more specific error messages and troubleshooting steps, consult the official SkyBiometry API error code documentation.