Skip to main content

Quickstart Guide

Get started with the vfrog.ai API in minutes. This guide will walk you through making your first API call.

Prerequisites​

Before you begin, you'll need:

  1. A vfrog.ai account - Sign up here
  2. An API key - Create one in the console

Your First API Call​

Let's make a simple request to recognize objects in an image using the synchronous endpoint.

Step 1: Get Your API Key​

  1. Log in to the vfrog.ai Console
  2. Navigate to API Keys in the sidebar
  3. Click Create API Key
  4. Give your key a name (e.g., "Development Key")
  5. Copy the generated API key - you'll need it for the next step
warning

Keep your API key secret! Don't commit it to version control or share it publicly.

Step 2: Make a Request​

Here's a simple example using cURL:

curl -X POST https://api.vfrog.ai/v1/cv/requests/sync \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "test-001",
    "image_url": "https://example.com/product.jpg"
  }'

Replace YOUR_API_KEY with your actual API key.

Step 3: Understand the Response​

The sync endpoint returns results directly in the response (max 29 seconds):

{
  "idempotency_id": "cv-request-uuid",
  "external_id": "test-001",
  "results": [
    {
      "class_name": "Product",
      "confidence": 0.95,
      "bounding_box": {
        "x": 100,
        "y": 150,
        "width": 200,
        "height": 250
      }
    }
  ],
  "status": "DONE"
}

Request Parameters​

The sync endpoint accepts the following parameters:

curl -X POST https://api.vfrog.ai/v1/cv/requests/sync \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "test-sync-001",
    "image_url": "https://example.com/product.jpg"
  }'

The sync endpoint returns results directly in the response (max 29 seconds):

{
  "idempotency_id": "cv-request-uuid",
  "external_id": "test-sync-001",
  "results": [
    {
      "class_name": "Product",
      "confidence": 0.95,
      "bounding_box": {
        "x": 100,
        "y": 150,
        "width": 200,
        "height": 250
      }
    }
  ],
  "status": "DONE"
}

Next Steps​

Now that you've made your first request, explore more:

Common Issues​

401 Unauthorized​

Make sure you're including the x-api-key header with a valid API key.

403 Forbidden​

Your API key may be suspended or revoked. Check the console.

400 Bad Request​

Check that your request body includes all required fields:

  • external_id (string)
  • image_url (valid URL)

429 Too Many Requests​

You've exceeded your rate limit. Check your quota in the console or upgrade your plan.