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.