Your First Request

Follow this step-by-step guide to make your first API request in under 5 minutes.

Step 1: Get Your API Key

After signing up, navigate to your dashboard and create an API key:

Click "Dashboard" in the top navigation
Go to "API Keys" tab
Click "Create New Key"
Copy your key (keep it secret!)

Step 2: Set Up Your Environment

Store your API key as an environment variable:

bash

export PERCEPTOS_API_KEY="pk_live_your_key_here"

Step 3: Install SDK or Use cURL

Option A: Using Python SDK

bash

pip install perceptos

Option B: Using Node.js

bash

npm install @perceptos/sdk

Option C: Using cURL

No installation needed! Use cURL directly in your terminal.

Step 4: Make Your First Request

Python

python

import perceptos
import os

api_key = os.getenv("PERCEPTOS_API_KEY")
client = perceptos.Client(api_key=api_key)

response = client.detect(
    image="https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"
)

print(response)

JavaScript

javascript

import { PerceptosClient } from "@perceptos/sdk";

const client = new PerceptosClient({
  apiKey: process.env.PERCEPTOS_API_KEY
});

const response = await client.detect({
  image: "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"
});

console.log(response);

cURL

bash

curl -X POST https://api.mashintoch.com/v1/detect \
  -H "Authorization: Bearer $PERCEPTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg",
    "confidence": 0.5,
    "max_objects": 10
  }'

Step 5: Handle the Response

The API returns a JSON response with detected objects:

json

{
  "request_id": "req_abc123def456",
  "processing_time": 245,
  "objects": [
    {
      "label": "cat",
      "confidence": 0.99,
      "bbox": [100, 150, 280, 420]
    },
    {
      "label": "couch",
      "confidence": 0.87,
      "bbox": [0, 300, 600, 480]
    }
  ]
}

Next Steps

1.Explore other endpoints (classify, ocr, faces, moderate)
2.Check out the API playground for interactive testing
3.Read the authentication docs to understand security
4.Join our Discord community for help and questions

Troubleshooting

401 Unauthorized

Your API key is missing or invalid. Check that you've set the PERCEPTOS_API_KEY environment variable correctly.

400 Bad Request

The request body is invalid. Make sure the image URL is accessible and the JSON format is correct.

429 Too Many Requests

You've exceeded the rate limit for your plan. Wait a moment before retrying or upgrade your plan.