Skip to content

PaddleOCR official API Go SDK

The Go SDK calls the PaddleOCR official API and submits OCR or document parsing jobs to hosted services. It does not run local PaddleOCR inference or load local models.

Install And Authenticate

First obtain an access token from the AI Studio Access Token page.

go get github.com/PaddlePaddle/PaddleOCR/api_sdk/go
export PADDLEOCR_ACCESS_TOKEN="your-access-token"

NewClient reads PADDLEOCR_ACCESS_TOKEN by default and also accepts an explicit token through WithToken.

Quick Start

client, err := paddleocr.NewClient()
if err != nil {
    return err
}

result, err := client.OCR(ctx, &paddleocr.OCRRequest{
    Model:   paddleocr.PPOCRv5,
    FileURL: "https://example.com/invoice.pdf",
})
if err != nil {
    return err
}
fmt.Println(result.JobID, len(result.Pages))

Use FilePath for a local file. Pass exactly one of FileURL or FilePath.

Public API

Common Go public methods include:

  • OCR(...): submit an OCR job, wait for completion, and return an OCR result.
  • ParseDocument(...): submit a document parsing job, wait for completion, and return a document parsing result.
  • SubmitOCR(...): submit only an OCR job and return a job object.
  • SubmitDocumentParsing(...): submit only a document parsing job and return a job object.
  • GetStatus(ctx, jobID): perform one non-blocking status request.
  • WaitOCRResult(ctx, job): wait for an OCR job and parse its result.
  • WaitDocumentParsingResult(ctx, job): wait for a document parsing job and parse its result.
  • SaveResource(...): save one resource URL.
  • SaveOCRResultResources(...): save resources referenced by an OCR result object.
  • SaveDocumentParsingResultResources(...): save resources referenced by a document parsing result object.

Choose Models

The model constants in the table are type-safe aliases for the official API model-name strings. They are serialized to the corresponding model name when the request is submitted. You can also pass the official API model-name string directly, for example Model: "PaddleOCR-VL-1.6".

Task Interfaces Default model Supported models Option type
OCR OCR, SubmitOCR, WaitOCRResult PPOCRv5 PPOCRv5 *OCROptions
Document parsing ParseDocument, SubmitDocumentParsing, WaitDocumentParsingResult PaddleOCRVL16 PPStructureV3, PaddleOCRVL, PaddleOCRVL15, PaddleOCRVL16 Use *PPStructureV3Options with PPStructureV3, and *PaddleOCRVLOptions with PaddleOCR-VL models.

Common mappings: PPOCRv5 maps to PP-OCRv5, PPStructureV3 maps to PP-StructureV3, PaddleOCRVL maps to PaddleOCR-VL, PaddleOCRVL15 maps to PaddleOCR-VL-1.5, and PaddleOCRVL16 maps to PaddleOCR-VL-1.6.

Configuration

Client Configuration

client, err := paddleocr.NewClient(
    paddleocr.WithRequestTimeout(30*time.Second),
    paddleocr.WithPollTimeout(5*time.Minute),
)

WithRequestTimeout limits one HTTP request, including submit, status, and resource downloads. WithPollTimeout limits the total wait time for OCR, ParseDocument, WaitOCRResult, and WaitDocumentParsingResult. Callers can also cancel requests through context.Context.

Override the service base URL via the PADDLEOCR_BASE_URL environment variable or WithBaseURL:

client, err := paddleocr.NewClient(
    paddleocr.WithBaseURL("https://my-proxy.com/paddle"),
)

Inject a custom *http.Client via WithHTTPClient for proxies, custom TLS, or retry policies:

client, err := paddleocr.NewClient(
    paddleocr.WithHTTPClient(myHTTPClient),
)

Request Options

Go SDK Options struct fields use PascalCase, serialized to camelCase automatically. Pointer fields set to nil are omitted. See the struct source or Official API Reference for complete field definitions.

OCROptions (common fields)

Field Type Description
UseDocOrientationClassify *bool Document orientation classification
UseDocUnwarping *bool Document unwarping
Visualize *bool Return visualization images

PPStructureV3Options (common fields)

Field Type Description
UseTableRecognition *bool Table recognition
UseFormulaRecognition *bool Formula recognition
UseChartRecognition *bool Chart recognition
PrettifyMarkdown *bool Markdown prettification

PaddleOCRVLOptions (common fields)

Field Type Description
UseLayoutDetection *bool Layout detection
UseChartRecognition *bool Chart recognition
Temperature *float64 Sampling temperature
PrettifyMarkdown *bool Markdown prettification

Error Handling

The Go SDK exposes typed errors compatible with errors.As, including AuthError, InvalidRequestError, RateLimitError, ServiceUnavailableError, APIError, NetworkError, JobFailedError, RequestTimeoutError, PollTimeoutError, ResponseFormatError, and ResultParseError.

Official API Reference

Quota and Error Codes

Comments