Documentation

Image Analysis API Reference

Upload and analyze images in a single API call

Simplest Way to Get Started

The Image Analysis API is the fastest way to describe an image. One HTTP call uploads your image and returns an AI-generated description, keyword tags, and any visible text detected in the image — no separate upload or polling steps required.

API Base URL

https://api.scopix.ai/api/v2

Sync Image Analysis

POST/api/v2/images/analyze

Upload an image and get its AI-generated description, tags, and extracted text in a single call. Accepts a multipart file upload, JSON with a URL, or JSON with a base64-encoded image. Waits up to timeout seconds (default 30) for the description to complete.

Request

json

# Multipart file upload (simplest):
curl -X POST https://api.scopix.ai/api/v2/images/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"

# With options:
curl -X POST https://api.scopix.ai/api/v2/images/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "content_category=real_estate" \
  -F "skip_duplicates=true" \
  -F "timeout=60"

# JSON with URL:
curl -X POST https://api.scopix.ai/api/v2/images/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/photo.jpg",
    "content_category": "general",
    "skip_duplicates": false,
    "timeout": 30
  }'

# JSON with base64:
curl -X POST https://api.scopix.ai/api/v2/images/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "<base64-encoded-image>",
    "content_category": "general"
  }'

// Parameters:
// - file: Image file (multipart) — OR —
// - url: Public image URL (JSON) — OR —
// - base64: Base64-encoded image (JSON)
// - content_category: Hint for tailored analysis (default: "general")
//     Values: auto, general, real_estate, architectural_design, product_photo,
//     blueprint, ce_plan, technical_diagram, mining, robotics,
//     artwork, screenshot, document, map, pid, pfd, construction,
//     facility_assessment
//     (auto = let Scopix classify automatically before processing)
// - skip_duplicates: Skip if identical file exists (default: false)
// - timeout: Max seconds to wait, 5-120 (default: 30)

Response

json

// The response is a discriminated union — check `status` first,
// then read only the fields declared for that variant.

// status: "completed"  (description finished within the timeout)
{
  "image_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "processing_time_ms": 2450.3,
  "description": "A modern open-plan kitchen with white marble countertops, stainless steel appliances, and pendant lighting over a central island.",
  "visible_text": null,
  "tags": ["kitchen", "modern", "marble", "pendant-lighting", "island"],
  "metadata": {
    "width": 4032,
    "height": 3024,
    "format": "JPEG",
    "size_bytes": 2458901,
    "content_type": "image/jpeg",
    "media_type": "image"
  },
  "confidence_score": null
}

// status: "processing"  (sync timeout exceeded — poll GET /job/{job_id})
{
  "image_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "processing_time_ms": 30000.0,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "poll_url": "/api/v2/job/550e8400-e29b-41d4-a716-446655440000"
}

// status: "failed"  (description failed — GET /job/{job_id} for detail)
{
  "image_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "processing_time_ms": 3120.7,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "poll_url": "/api/v2/job/550e8400-e29b-41d4-a716-446655440000",
  "error": null
}

// status: "skipped"  (content-hash match on an existing image)
{
  "image_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "skipped",
  "processing_time_ms": 42.1
}

Discriminated response — check `status` first

The response body always includes status, and every other field depends on which status you got. completed carries description / tags / metadata. processing and failed carry job_id and poll_url so you can follow up via GET /job/{job_id}. skipped carries only the existing image_id (call the files resource for detail). Never test for field presence before checking status.

Async Image Analysis

POST/api/v2/images/analyze/async

Same input as POST /images/analyze, but always returns immediately with HTTP 202 and a job_id. Use this when you want to fire-and-forget or process many images concurrently.

Request

json

# Same input formats as POST /images/analyze:
curl -X POST https://api.scopix.ai/api/v2/images/analyze/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"

# Or with JSON:
curl -X POST https://api.scopix.ai/api/v2/images/analyze/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

Response

json

// 202 Accepted — always returned
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "poll_url": "/api/v2/job/550e8400-e29b-41d4-a716-446655440000"
}

Job Status

GET/api/v2/job/{job_id}

Poll the status of any async image analysis operation. Returns full results when complete. The progress field is included for multi-file session jobs only.

Response

json

// Like /images/analyze, /job/{job_id} is a discriminated union tagged
// by `status`. Check `status` first; only the fields declared for
// that variant are present.

// status: "processing"
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "image",
  "status": "processing",
  "created_at": "2026-03-30T12:00:00Z",
  "progress": null
}

// status: "completed"
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "image",
  "status": "completed",
  "created_at": "2026-03-30T12:00:00Z",
  "completed_at": "2026-03-30T12:00:03Z",
  "results": [
    {
      "image_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "description": "A modern open-plan kitchen with white marble countertops...",
      "visible_text": null,
      "tags": ["kitchen", "modern", "marble"],
      "confidence_score": null
    }
  ],
  "progress": null
}

// status: "failed"
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "image",
  "status": "failed",
  "created_at": "2026-03-30T12:00:00Z",
  "completed_at": "2026-03-30T12:00:03Z",
  "error_message": "VLM provider unavailable",
  "progress": null
}

Polling Recommendation

Poll every 2-3 seconds. Most single-image descriptions complete in under 5 seconds. The status field transitions from processing to either completed or failed.

Content Categories

The content_category parameter hints at the type of image, enabling domain-specific AI analysis with tailored extraction fields.

Category	Use For
`auto`	Let Scopix classify the image automatically before processing
`general`	Any image (default)
`real_estate`	Property photos, room interiors, exteriors
`architectural_design`	Architectural spaces, furniture, decor
`product_photo`	Product images, e-commerce
`blueprint`	Architectural blueprints, floor plans
`technical_diagram`	Engineering diagrams, schematics
`ce_plan`	Civil engineering plans
`mining`	Mining operations, geological surveys
`robotics`	Robotics scenes for ML dataset curation (objects, affordances, grasp strategies)
`pid`	Piping and Instrumentation Diagrams (ISA S5.1)
`pfd`	Process Flow Diagrams
`artwork`	Paintings, illustrations, art
`screenshot`	Screenshots, UI captures
`document`	Scanned documents, forms
`map`	Maps, satellite imagery
`construction`	Construction sites, active building projects
`facility_assessment`	Building condition assessments (FCA/PCA), deficiency inspections

Documentation

Image Analysis API Reference

Simplest Way to Get Started

API Base URL

Sync Image Analysis

Request

Response

Discriminated response — check `status` first

Async Image Analysis

Request

Response

Job Status

Response

Polling Recommendation

Content Categories

Related

API Quick Start

Files Reference

Code Examples