Image OCR

Updated at:

Use the Content Moderation Go SDK to extract text from images and structured cards such as ID cards.

Which mode do you need?

ModeWhat it recognizesWhen to use it
General OCRText in everyday images (signs, screenshots, documents)Detecting free-form text in arbitrary images
Structured card OCRFields on standardized cards (ID cards)Extracting structured data from identity documents

Both modes use the same ImageSyncScanRequest operation with scenes set to ocr. For structured card recognition, add the extras field with the card type.

For a full list of request and response parameters, see Image OCR detection API.

Limitations

  • Accepts only public HTTP or HTTPS image URLs — local files and binary data are not supported.

  • Maximum URL length: 2,048 characters.

Prerequisites

Before you begin, ensure that you have:

  • Go dependencies installed. See Installation for the required Go version. Using a different version causes operation calls to fail.

  • A RAM user AccessKey ID and AccessKey secret stored as environment variables:

    • ALIBABA_CLOUD_ACCESS_KEY_ID

    • ALIBABA_CLOUD_ACCESS_KEY_SECRET

Note

Never hardcode credentials in your source code. Read them from environment variables as shown in the examples below.

Detect text in an image

ImageSyncScanRequest submits a synchronous OCR task and returns results in the same call — no polling required.

Supported regions: cn-shanghai, cn-beijing, cn-shenzhen, ap-southeast-1

General OCR

package main

import (
    "encoding/json"
    "fmt"
    "os"
    "strconv"

    "github.com/aliyun/alibaba-cloud-sdk-go/services/green"
)

func main() {
    // Reuse the client across calls to avoid repeated connection overhead.
    client, _err := green.NewClientWithAccessKey(
        "cn-shanghai",
        os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
        os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    )
    if _err != nil {
        fmt.Println(_err.Error())
        return
    }

    task := map[string]interface{}{
        "dataId": "<your-data-id>",   // Unique ID for tracking this request
        "url":    "<your-image-url>",
    }

    content, _ := json.Marshal(map[string]interface{}{
        "tasks":   task,
        "scenes":  [...]string{"ocr"},
        "bizType": "<your-business-scenario>",
    })

    request := green.CreateImageSyncScanRequest()
    request.SetContent(content)

    response, _err := client.ImageSyncScan(request)
    if _err != nil {
        fmt.Println(_err.Error())
        return
    }
    if response.GetHttpStatus() != 200 {
        fmt.Println("response not success. status:" + strconv.Itoa(response.GetHttpStatus()))
        return
    }
    fmt.Println(response.GetHttpContentString())
}

Replace the following placeholders before running:

PlaceholderDescriptionExample
<your-data-id>Unique identifier for the image in your systemimg-20240101-001
<your-image-url>Public HTTP or HTTPS URL of the imagehttps://example.com/sample.jpg
<your-business-scenario>Your configured business scenario (bizType)default

Structured card OCR

To extract text from a structured card, add the extras field with the card parameter. The following example detects the front of an ID card.

// Recognize the front of an ID card.
cardExtras := map[string]interface{}{"card": "id-card-front"}

// To recognize the back of an ID card instead, use:
// cardExtras := map[string]interface{}{"card": "id-card-back"}

content, _ := json.Marshal(map[string]interface{}{
    "tasks":   task,
    "scenes":  [...]string{"ocr"},
    "bizType": "<your-business-scenario>",
    "extras":  cardExtras,
})

The card parameter accepts the following values:

ValueCard side
id-card-frontFront of an ID card
id-card-backBack of an ID card

What's next