upstage-information-extraction

Upstage Information Extraction

Extract structured data from documents using custom JSON schemas. Also supports prebuilt models for receipts, invoices, and trade documents.

Quick Start

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UPSTAGE_API_KEY"],
    base_url="https://api.upstage.ai/v1/information-extraction"
)

response = client.chat.completions.create(
    model="information-extract",
    messages=[{
        "role": "user",
        "content": [{"type": "image_url", "image_url": {"url": "https://example.com/invoice.pdf"}}]
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "invoice_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "invoice_number": {"type": "string", "description": "Invoice ID"},
                    "total_amount": {"type": "string", "description": "Total amount with currency"},
                    "date": {"type": "string", "description": "Invoice date in YYYY-MM-DD"}
                }
            }
        }
    }
)
print(response.choices[0].message.content)

API Key: Always use os.environ["UPSTAGE_API_KEY"]. Get your key at console.upstage.ai.

---

Endpoints

Mode	Endpoint
Sync	POST https://api.upstage.ai/v1/information-extraction
Async	POST https://api.upstage.ai/v1/information-extraction/async
Status	GET https://api.upstage.ai/v1/information-extraction/jobs/{job_id}

• OpenAI SDK compatible: Set base_url to https://api.upstage.ai/v1/information-extraction

Parameters

Parameter	Type	Required	Description
model	string	Yes	information-extract or information-extract-nightly
messages	array	Yes	Single user message with image_url
response_format	object	Yes	Extraction schema (JSON Schema format)
mode	string	No	standard (default) or enhanced
location	boolean	No	Return coordinates (default: false)
confidence	boolean	No	Return confidence scores (default: false)
split	boolean	No	Split multi-document files (default: false)

Limits

Item	Sync	Async
Max pages	100	1,000
Max properties	100	5,000
Max schema chars	15,000	120,000

Schema Rules

• Top-level properties: only string, integer, number, array allowed (no objects)
• No nested arrays
• Total character length of all property names must be under 10,000
• For automatic schema generation, use upstage-schema-generation skill

Response Structure

{
  "choices": [
    {
      "message": {
        "content": "{\"invoice_number\": \"INV-001\", \"total_amount\": \"$1,234.56\", \"date\": \"2026-01-15\"}"
      }
    }
  ],
  "usage": {"prompt_tokens": 500, "completion_tokens": 50}
}

content is a JSON string. Parse with json.loads().

---

Prebuilt Models

Ready-to-use models that require no schema definition.

Model	Document Type
receipt-extraction	Receipts
air-waybill-extraction	Air waybills
bill-of-lading-and-shipping-request-extraction	Bills of lading / shipping requests
commercial-invoice-and-packing-list-extraction	Commercial invoices / packing lists
kr-export-declaration-certificate-extraction	Korean export declaration certificates

Prebuilt Usage Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UPSTAGE_API_KEY"],
    base_url="https://api.upstage.ai/v1/information-extraction"
)

response = client.chat.completions.create(
    model="receipt-extraction",
    messages=[{
        "role": "user",
        "content": [{"type": "image_url", "image_url": {"url": "https://example.com/receipt.jpg"}}]
    }]
)
print(response.choices[0].message.content)

Prebuilt models are called without response_format.

---

Async Processing (Large Documents)

import os
import time
import requests

api_key = os.environ["UPSTAGE_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

# 1. Submit async job
response = requests.post(
    "https://api.upstage.ai/v1/information-extraction/async",
    headers=headers,
    json={
        "model": "information-extract",
        "messages": [{"role": "user", "content": [{"type": "image_url", "image_url": {"url": "FILE_URL"}}]}],
        "response_format": {"type": "json_schema", "json_schema": {"name": "schema", "schema": {...}}}
    }
)
job_id = response.json()["id"]

# 2. Poll for results
while True:
    status = requests.get(
        f"https://api.upstage.ai/v1/information-extraction/jobs/{job_id}",
        headers=headers
    ).json()
    if status["status"] == "completed":
        print(status["choices"][0]["message"]["content"])
        break
    time.sleep(5)

Output Files

• Default: write extracted JSON to <system-temp>/<input-stem>.extracted.json (e.g., /tmp/invoice.extracted.json). Use tempfile.gettempdir() for cross-platform code.
• Override: if the user specifies an output path, use it.
• Always print the resolved absolute path in your response so the user can locate the file.

Tips

• enhanced mode improves accuracy on complex tables/images but is slower.
• Set confidence: true to get per-field confidence scores for quality filtering.
• Schema design is critical for extraction quality. Use upstage-schema-generation skill for automatic generation.
• split: true is useful when a single file contains multiple documents.