Scopix

Documentation

Extraction API Reference

Extract structured data from images using a JSON Schema definition

Schema-Driven Extraction

  • • How it works: Define a JSON Schema, provide an image, and receive structured data matching your schema
  • • Powered by: Google Gemini controlled generation for schema-enforced output
  • • Reusable schemas: Save schemas via the Custom Extraction Schemas API and reference them by ID
  • • Image sources: URL, base64, or file_id of an already-uploaded image

Extract Structured Data

POST/api/v2/extract

Extract structured data from an image using a JSON Schema. Provide exactly one image source and exactly one schema source.

Request

json
{
  "image_url": "https://example.com/photo.jpg",
  "schema": {
    "type": "object",
    "properties": {
      "item_name": {"type": "string", "description": "Name of the item"},
      "quantity": {"type": "integer", "description": "Number of items"},
      "condition": {
        "type": "string",
        "enum": ["new", "good", "fair", "poor"],
        "description": "Item condition"
      }
    },
    "required": ["item_name", "quantity"]
  },
  "prompt": "This is a warehouse inventory photo",
  "analysis_level": "default"
}


// Image source (exactly one required):
//   image_url: URL of the image
//   image_base64: base64-encoded image data
//   file_id: UUID of an already-uploaded image
//
// Schema source (exactly one required):
//   schema: inline JSON Schema (root type must be "object")
//   custom_schema_id: UUID of a saved schema (see Custom Extraction Schemas API)
//
// prompt: optional context to improve accuracy, max 2000 chars
// analysis_level: controls output token budget
//   "quick"    — 4K tokens
//   "default"  — 8K tokens (default)
//   "standard" — 8K tokens
//   "thorough" — 16K tokens
//   "critical" — 16K tokens

Response

json
{
  "extracted_data": {
    "item_name": "Steel Beam",
    "quantity": 12,
    "condition": "good"
  },
  "processing_time_ms": 2340,
  "provider": "google",
  "model": "gemini-3-flash-preview",
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 48,
    "thinking_tokens": null
  }
}

Schema Rules

JSON Schema Constraints

  • • Root type: Must be "object"
  • • Max depth: 3 levels of nesting
  • • Max properties per object: 50
  • • Max total nodes: 200
  • • Max schema size: 32KB
  • • Allowed types: string, integer, number, boolean, array, object
  • • Supported composition: anyOf only ($ref, allOf, oneOf are not supported)

Using Saved Schemas

Instead of providing an inline schema, you can reference a saved schema by its UUID. Create and manage schemas via the Custom Extraction Schemas API.

POST/api/v2/extract

Extract using a saved schema. If the saved schema has a prompt_hint and no prompt is provided, the hint is used automatically.

Request

json
{
  "image_url": "https://example.com/invoice.jpg",
  "custom_schema_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "analysis_level": "thorough"
}


// custom_schema_id: UUID of a saved extraction schema
// Cannot be combined with "schema" — use one or the other

Response

json
{
  "extracted_data": {
    "vendor": "Acme Corp",
    "invoice_number": "INV-2026-0042",
    "line_items": [
      {"description": "Widget A", "quantity": 100, "unit_price": 4.99},
      {"description": "Widget B", "quantity": 50, "unit_price": 9.99}
    ],
    "total": 998.50
  },
  "processing_time_ms": 3120,
  "provider": "google",
  "model": "gemini-3-flash-preview",
  "usage": {
    "input_tokens": 1840,
    "output_tokens": 125,
    "thinking_tokens": null
  }
}

Error Responses

Common Errors

  • • 422: Missing or multiple image sources, missing or multiple schema sources, prompt too long
  • • 400: Invalid schema (depth, node count, unsupported types/keywords), invalid analysis_level, saved schema not found (CUSTOM_SCHEMA_NOT_FOUND), invalid base64 data, file_id image not found
  • • 403: Missing EDIT permission on IMAGES resource
  • • 500: VLM provider unavailable, extraction returned empty result

Related

Custom Extraction Schemas

Save and manage reusable extraction schemas

Files Reference

Upload images and review extraction results