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

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)

PPStructureV3Options (common fields)

PaddleOCRVLOptions (common fields)

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

• PP-OCRv5 API
• PP-StructureV3 API
• PaddleOCR-VL API
• PaddleOCR-VL-1.5 API

Quota and Error Codes

• API Quota Rules and Error Code Description