Documentation

Everything you need to integrate Pixicular API photo analysis into your app.

Getting Started

Get up and running with the Pixicular API in just a few minutes.

Create an account

Get your API key

Generate an API key from your dashboard.

Make your first request

Use the code examples in the POST /v1/detect or POST /v1/detect-from-url section below to make your first detection request.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer apd_live_your_api_key_here

API keys have the format: apd_live_... or apd_test_...

Use apd_test_... keys for development — they work identically but are tracked separately. Use apd_live_... keys in production.

POST/v1/detectand/v1/detect-from-url

Analyze an image to detect if it was AI-generated. Supports both file upload (multipart) and URL submission (JSON).

Parameters

Parameter	Type	Required	Description
`file`	File	Required*	Image file (multipart upload)
`url`	String	Required*	Image URL (JSON body)
`services`	String	Required	Comma-separated list of services to run. Available: detect-age, detect-labels.

* Either file or url is required

Code Examples

File Upload (multipart/form-data)

curl -X POST "https://api-eu.pixicular.com/v1/detect" \
  -H "Authorization: Bearer apd_live_your_api_key_here" \
  -F "services=detect-age" \
  -F "file=@/path/to/image.jpg"

URL Submission (application/json)

curl -X POST "https://api-eu.pixicular.com/v1/detect-from-url" \
  -H "Authorization: Bearer apd_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "services": "detect-age",
    "url": "https://example.com/image.jpg"
  }'

Response

{
  "success": true,
  "services": {
        "detect-age": {
            "faces": [
                {
                    "ageRange": {
                        "low": 22,
                        "high": 28
                    },
                    "ageEstimate": 25,
                    "confidence": 99.99726104736328
                }
            ]
        }
  },
  "photo": {
      "id": "photo_Dy2csYO9nhYgdDxn9B",
      "status": "COMPLETED"
  },
  "creditCost": 1,
  "processingTimeMs": 1250,
  "processedAt": "2025-12-31T23:59:59.002Z"
}

Service response examples

{
  "services": {
    "detect-age": {
      "faces": [
        {
          "ageRange": { "low": 25, "high": 35 },
          "ageEstimate": 30,
          "confidence": 98.4
        }
      ]
    }
  }
}

{
  "services": {
    "detect-labels": {
      "labels": [
        {
          "name": "Person",
          "confidence": 99.8,
          "categories": ["Person Description"]
        }
      ]
    }
  }
}

GET/v1/history

Retrieve a paginated list of your operation history.

Query Parameters

Parameter	Type	Default	Description
`page`	Integer	`1`	Page number
`perPage`	Integer	`50`	Results per page (max 100)

Code Examples

curl "https://api-eu.pixicular.com/v1/history?page=1&perPage=50" \
  -H "Authorization: Bearer apd_live_your_api_key_here"

Response

{
  "data": [
    {
      "requestId": "req_wUKl0im7IZg4bCefnE",
      "operationId": "op_QtLqxId519-4muCl_L",
      "services": {
        "detect-age": {
          "faces": [
            { "ageRange": { "low": 30, "high": 40 }, "ageEstimate": 35, "confidence": 97.2 }
          ]
        }
      },
      "processedAt": "2025-12-31T23:59:59.002Z"
    }
  ],
  "meta": {
    "pagination": {
      "currentPage": 1,
      "perPage": 50,
      "totalRecords": 150,
      "totalPages": 3,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}

GET/v1/history/:requestId

Retrieve detailed information about a specific operation result.

Code Examples

curl "https://api-eu.pixicular.com/v1/history/req_wUKl0im7IZg4bCefnE" \
  -H "Authorization: Bearer apd_live_your_api_key_here"

Response

{
  "data": {
    "requestId": "req_wUKl0im7IZg4bCefnE",
    "processedAt": "2025-12-31T23:59:59.002Z",
    "services": {
        "detect-age": {
            "faces": [
                {
                    "ageRange": {
                        "low": 22,
                        "high": 28
                    },
                    "ageEstimate": 25,
                    "confidence": 99.99726104736328
                }
            ]
        },
    },
    "photo": {
        "id": "photo_Dy2csYO9nhYgdDxn9B",
        "status": "COMPLETED"
    },
    "creditCost": 3,
    "processingTimeMs": 1156,
    "processedAt": "2025-12-31T23:59:59.002Z"
  }
}

Photo Analysis Services

Pass a comma-separated list of service IDs in the services field. Each service costs 1 credit per request.

detect-age1 credit

Estimates the age range of every face detected in the image.

{
  "faces": [
    {
      "ageRange": { "low": 25, "high": 35 },
      "ageEstimate": 30,
      "confidence": 99.3
    }
  ]
}

detect-labels1 credit

Detects objects, scenes, and activities in the image with confidence scores and category tags.

{
  "labels": [
    { "name": "Person", "confidence": 99.8, "categories": ["People"] },
    { "name": "Outdoors", "confidence": 87.3, "categories": ["Nature"] },
    { "name": "Mountain", "confidence": 74.1, "categories": ["Nature"] }
  ]
}

detect-moderation1 credit

Detects unsafe or sensitive content — nudity, violence, drugs, hate symbols, and more. Returns a hierarchical list of moderation labels with confidence scores.detected is true when any label is found.

{
  "detected": true,
  "labels": [
    {
      "name": "Suggestive",
      "parentName": "",
      "confidence": 90.5
    },
    {
      "name": "Female Swimwear Or Underwear",
      "parentName": "Suggestive",
      "confidence": 90.5
    }
  ]
}

detect-text1 credit

Extracts lines of text found in the image using OCR. Only full lines are returned (individual words are omitted).

{
  "detections": [
    { "detectedText": "Hello World", "type": "LINE", "confidence": 99.1 },
    { "detectedText": "Open 9am – 5pm", "type": "LINE", "confidence": 96.4 }
  ]
}

detect-face-emotions1 credit

Returns confidence scores for eight emotions — HAPPY, SAD, ANGRY, SURPRISED, DISGUSTED, CALM, CONFUSED, and FEAR — for each face detected.

{
  "faces": [
    {
      "faceConfidence": 99.9,
      "emotions": [
        { "type": "HAPPY", "confidence": 97.2 },
        { "type": "CALM", "confidence": 1.5 },
        { "type": "SURPRISED", "confidence": 0.8 }
      ]
    }
  ]
}

Limits & Pricing

General Limits

Max file size

10MB per image

Supported formats

PNG, JPG, JPEG, GIF, WebP

Rate limit

Detection: 60 req/min, History: 600 req/min

Image dimensions

100x100 to 4096x4096 px

Pricing Plans

Plan	Price	Included	Overage
Developer	$0/mo	100 operations	-
Launch	$25/mo	1,000 operations	$0.015 per extra operation
Scale	$99/mo	10,000 operations	$0.010 per extra operation
Business	$299/mo	100,000 operations	$0.005 per extra operation
Enterprise	Custom	Unlimited	Custom

A request is one uploaded and processed photo via Pixicular API (or via the Pixicular website), regardless of how many services it includes.

An operation is one service run on a request.

So if 3 services are selected on one request, it counts as 3 operations. For example, if there is one request and it has two services defined, `detect-age` and `detect-labels`, it counts as two operations.

View full pricing details

Usage Limits & Overage Policy

Developer plan: Currently includes a 14-day trial and is hard-capped at 100 operations. Once reached, operations are blocked until you upgrade.

Paid plans (Launch, Scale, Business):Once 100% of your monthly usage is reached, you will be charged per extra operation at your plan's overage rate. By default, when you reach 200% of the original plan usage, operations will be rate-limited (HTTP 429) until the next payment period or until you upgrade your plan.

Email alerts: You will receive email notifications at 80%, 90%, and 100% of your monthly usage limit.

To request a higher overage cap for your plan, contact us at support@pixicular.com.

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

400Bad Request

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid services: unknown-service. Available: detect-age,detect-labels"
}

401Unauthorized

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

429Rate Limited (too many requests)

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please wait 15 minutes."
}

429Monthly Limit Exceeded

{
  "statusCode": 429,
  "error": "Usage Limit Exceeded",
  "message": "Requests rate-limited because usage has reached 200% of your monthly limit for this period."
}

Need Help?

Visit your Dashboard to monitor usage

View Pricing plans and upgrade options

Email us at support@pixicular.com for general support

Contact support for Enterprise plan inquiries