Documentation

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

See implementation guides for OCR text extraction, ID document OCR for KYC, and UGC image moderation.

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.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.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.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.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