API Documentation

Overview

The Vision Grader API allows you to process device images for quality assessment. The process involves two steps: first upload images to get URLs, then submit those URLs for analysis along with an IMEI identifier and API key.

Authentication

All API requests require a valid API key. Include your key in the request body when making calls to the API endpoints.

Endpoints

POSThttps://vision-grader.pandas.io/api/upload

Upload individual images and get their public URLs

POSThttps://vision-grader.pandas.io/api/process

Process uploaded images for quality assessment and return analysis results

Process Flow

Two-Step Process: First upload images to get URLs, then submit URLs for analysis.

Step 1: Upload Images

Upload each image individually to /api/upload

  • • Send image file, section, and optional IMEI
  • • Receive public URL for each uploaded image
  • • Images are automatically processed and optimized

Step 2: Process Analysis

Submit all image URLs to /api/process

  • • Send JSON with image URLs, sections, API key, and optional IMEI
  • • Receive comprehensive analysis results
  • • Session is created and stored in database

Upload Endpoint

Request Format (Form Data)

  • image (file) - Image file to upload
  • section (string) - Section identifier for the image
  • imei (string, optional) - Device IMEI identifier

Response Format

{
  "success": true,
  "url": "https://storage.example.com/images/123456789012345/front/1703123456789_image.jpg",
  "path": "123456789012345/front/1703123456789_image.jpg",
  "size": 123456,
  "section": "front"
}

Process Endpoint

Request Format (JSON)

  • key (string) - Your API key for authentication
  • images (array) - Array of image objects with url and section
  • imei (string, optional) - Device IMEI identifier for tracking

Image Object Structure

  • url (string) - Public URL of the uploaded image
  • section (string) - Section identifier (front, lcd, back, cameras, body)
  • path (string, optional) - Storage path of the image
  • size (number, optional) - File size in bytes

Available Sections

  • front - Front side of the device
  • lcd - LCD screen
  • back - Back side of the device
  • cameras - Back camera lenses
  • body - Body frame

Code Examples

Node.js Example

const FormData = require('form-data');
const fs = require('fs');

async function uploadImage(filePath, section, imei) {
    const formData = new FormData();
    formData.append('image', fs.createReadStream(filePath));
    formData.append('section', section);
    if (imei) formData.append('imei', imei);

    const response = await fetch('https://vision-grader.pandas.io/api/upload', {
        method: 'POST',
        body: formData
    });

    if (!response.ok) {
        throw new Error('Upload failed');
    }

    return await response.json();
}

async function createSession() {
    const imei = '123456789012345';
    const apiKey = 'your-api-key-here';
    
    try {
        // Step 1: Upload all images
        const uploadPromises = [
            uploadImage('./front-1.jpg', 'front', imei),
            uploadImage('./front-2.jpg', 'front', imei),
            uploadImage('./front-3.jpg', 'front', imei),
            uploadImage('./front-4.jpg', 'front', imei),
            uploadImage('./back-1.jpg', 'back', imei),
            uploadImage('./back-2.jpg', 'back', imei)
        ];

        const uploadedImages = await Promise.all(uploadPromises);
        
        // Step 2: Process analysis
        const processData = {
            key: apiKey,
            imei: imei,
            images: uploadedImages.map(img => ({
                url: img.url,
                section: img.section
            }))
        };

        const response = await fetch('https://vision-grader.pandas.io/api/process', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(processData)
        });
        
        const result = await response.json();
        
        if (response.ok) {
            console.log('Session created successfully:', result);
            console.log('Session ID:', result.sessionId);
            console.log('Analysis results:', result.analysis);
        } else {
            console.error('Error:', result.error);
        }
    } catch (error) {
        console.error('Request failed:', error);
    }
}

createSession();

Python Example

import requests
import json

def upload_image(file_path, section, imei=None):
    url = 'https://vision-grader.pandas.io/api/upload'
    
    files = {'image': open(file_path, 'rb')}
    data = {'section': section}
    if imei:
        data['imei'] = imei
    
    response = requests.post(url, files=files, data=data)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f'Upload failed: {response.text}')

def create_session():
    imei = '123456789012345'
    api_key = 'your-api-key-here'
    
    try:
        # Step 1: Upload all images
        image_files = [
            ('./front-1.jpg', 'front'),
            ('./front-2.jpg', 'front'),
            ('./front-3.jpg', 'front'),
            ('./front-4.jpg', 'front'),
            ('./back-1.jpg', 'back'),
            ('./back-2.jpg', 'back')
        ]
        
        uploaded_images = []
        for file_path, section in image_files:
            result = upload_image(file_path, section, imei)
            uploaded_images.append(result)
        
        # Step 2: Process analysis
        process_data = {
            'key': api_key,
            'imei': imei,
            'images': [
                {
                    'url': img['url'],
                    'section': img['section']
                }
                for img in uploaded_images
            ]
        }
        
        response = requests.post(
            'https://vision-grader.pandas.io/api/process',
            headers={'Content-Type': 'application/json'},
            data=json.dumps(process_data)
        )
        
        result = response.json()
        
        if response.status_code == 200:
            print('Session created successfully:', result)
            print('Session ID:', result['sessionId'])
            print('Analysis results:', result['analysis'])
        else:
            print('Error:', result.get('error', 'Unknown error'))
            
    except Exception as e:
        print('Request failed:', e)

create_session()

cURL Example

# Step 1: Upload images
curl -X POST https://vision-grader.pandas.io/api/upload \
  -F "image=@./front-1.jpg" \
  -F "section=front" \
  -F "imei=123456789012345"

curl -X POST https://vision-grader.pandas.io/api/upload \
  -F "image=@./front-2.jpg" \
  -F "section=front" \
  -F "imei=123456789012345"

# ... upload all other images ...

# Step 2: Process analysis
curl -X POST https://vision-grader.pandas.io/api/process \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-api-key-here",
    "imei": "123456789012345",
    "images": [
      {
        "url": "https://storage.example.com/images/123456789012345/front/1703123456789_front-1.jpg",
        "section": "front"
      },
      {
        "url": "https://storage.example.com/images/123456789012345/front/1703123456789_front-2.jpg",
        "section": "front"
      }
    ]
  }'

Response Format

Upload Success Response (200)

{
  "success": true,
  "url": "https://storage.example.com/images/123456789012345/front/1703123456789_image.jpg",
  "section": "front"
}

Process Success Response (200)

Important: The analysis field contains the crucial quality assessment results for each device section.

{
  "success": true,
  "message": "Session created successfully",
  "sessionId": "uuid-of-created-session",
  "imei": "123456789012345",
  "analysis": {
    "front": {
      "score": 85,
      "issues": ["minor scratch on screen", "dust particles"],
      "recommendations": ["clean screen before assessment", "check for additional damage"]
    },
    "back": {
      "score": 78,
      "issues": ["crack in corner", "scratches"],
      "recommendations": ["repair needed", "assess internal damage"]
    }
  },
  "images": [
    {
      "url": "https://storage.example.com/images/123456789012345/front/1703123456789_image.jpg",
      "section": "front",
      "path": "123456789012345/front/1703123456789_image.jpg",
      "size": 123456
    }
  ]
}

Error Response (400/500)

{
  "error": "Invalid request: key not found"
}

Analysis Results

The analysis field contains detailed quality assessment results for each device section. This is the primary output of the API and includes:

  • score - Quality score (0-100) for the section
  • issues - Array of detected problems or defects
  • recommendations - Suggested actions or improvements

Error Codes

400 - Bad Request: Missing or invalid parameters
400 - Invalid API key
400 - Invalid image format
400 - Missing image URL or section
500 - Internal server error

Image Requirements

  • Supported formats: JPEG, PNG, GIF, WebP
  • Images are automatically resized to max width of 1028px while maintaining aspect ratio
  • Images are converted to JPEG format with high quality (100%)
  • Maximum 4 images per section
  • File size limit: Determined by your server configuration

Rate Limits

Rate limits are determined by your API key tier. Please contact support for specific limits.

Support

For technical support or questions about the API, please contact your account manager or reach out to our support team.