Upstage Information Extraction#

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

Quick Start#

python

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#

ModeEndpointSyncPOST https://api.upstage.ai/v1/information-extractionAsyncPOST https://api.upstage.ai/v1/information-extraction/asyncStatusGET 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#

ParameterTypeRequiredDescriptionmodelstringYesinformation-extract or information-extract-nightly``messagesarrayYesSingle user message with image_url``response_formatobjectYesExtraction schema (JSON Schema format)modestringNostandard (default) or enhanced``locationbooleanNoReturn coordinates (default: false)confidencebooleanNoReturn confidence scores (default: false)splitbooleanNoSplit multi-document files (default: false)

Limits#

ItemSyncAsyncMax pages1001,000Max properties1005,000Max schema chars15,000120,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#

json

{
  "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.

ModelDocument Typereceipt-extractionReceiptsair-waybill-extractionAir waybillsbill-of-lading-and-shipping-request-extractionBills of lading / shipping requestscommercial-invoice-and-packing-list-extractionCommercial invoices / packing listskr-export-declaration-certificate-extractionKorean export declaration certificates

Prebuilt Usage Example#

python

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)#

python

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.