Image Annotation Callback

Update:

API Overview

After manual image annotation, the platform sends the original moderation data and updated annotation to your callback URL. Configure it under Project > Service Configuration > Annotation API Callback. Manual annotations can be updated individually or in batches under Project > Data Query.

POSTcallbackUrl

Request Parameters

Request Headers

All headers are required.

Header Value Description
Content-Type application/json;charset=UTF-8 Request body format
Accept application/json;charset=UTF-8 Expected response format
X-AppId — Project ID from Service Configuration
X-TimeStamp — UTC request time in W3C format. Example: 2026-09-30T02:30:00Z. Use the current request time.
Authorization — Signature calculated as described below

Request Body

Parameter Type Required Description
appId String Required Project ID
imageData Array Required Original image moderation data
imageData[].extra Object Optional Extension fields passed through from the original moderation request. Omitted when the original record has no extra, or the value is null or an empty string
markData Object Required Updated manual annotation
markData.markResult Number Required Manual annotation result
markData.markTag Array<Number> Required Manual annotation category codes

Request Example

{
  "appId": "81000001",
  "imageData": [
    {
      "taskId": "us_b0db751223584cf5af9d5c469bb9e4d1_1694159664104",
      "strategyId": "DEFAULT",
      "url": "https://example.com/image.jpg",
      "displayUrl": "https://example.com/image.jpg",
      "code": 0,
      "result": 0,
      "imageCheckType": [],
      "tags": [],
      "subTags": [],
      "userId": null,
      "md5": "CC6300BC04F46883944D0C38BCDA6A02",
      "extra": {
        "roomId": "10001",
        "bizId": "abc"
      }
    }
  ],
  "markData": {
    "markResult": 2,
    "markTag": [
      130
    ]
  }
}

Request Signature

Send the Base64-encoded HMAC-SHA256 signature in the Authorization header. This callback uses the complete configured CallbackUrl in the signing string.

  1. Compute SHA-256 over the original received request body bytes (UTF-8 JSON), and encode the digest as lowercase hexadecimal. Do not reserialize, format, or change escaping before verification:

    CanonicalizedQueryString = hex(sha256(jsonBody))

  2. Join these components with an ASCII newline (\n), without a trailing newline:

    StringToSign = HTTPMethod + "\n"
             + CallbackUrl + "\n"
             + CanonicalizedQueryString + "\n"
             + "X-AppId:" + SAME_APPID_IN_HEADER + "\n"
             + "X-TimeStamp:" + SAME_TIMESTAMP_IN_HEADER
    Signing Parameter Value
    HTTPMethod POST
    CallbackUrl Exact complete URL configured for Annotation API Callback, including scheme, port if present, path, and query parameters if present
    SAME_APPID_IN_HEADER Exact value of the X-AppId header
    SAME_TIMESTAMP_IN_HEADER Exact value of the X-TimeStamp header

  3. Compute HMAC-SHA256 over StringToSign using secretKey, then Base64-encode the binary digest, not its hexadecimal text, and send it in Authorization. Use the callback key shown under Project > Service Configuration > Annotation API Callback, not the corporation secret or the image moderation project secret.