Callback

POSThttps://api.newportai.com/api/async/*

The DreamAPI Callback feature enables event-driven result delivery for all async API tasks. By adding callback parameters to your async request, DreamAPI will automatically send a POST request to your specified callback URL once the task is completed, eliminating the need for continuous polling.

Add callback parameters to any /api/async/* request to enable automatic result notification.
DreamAPI sends a POST webhook to your callback URL when task processing finishes.
Supports HMAC-SHA256 signature verification to ensure callback authenticity.
Provides two callback modes: full result data or status-only notification.

Request Headers

Content-Type string Required

Enum: application/json

Authorization string Required

Bearer authentication token. Example: Bearer {{APIKey}}.

Request Body

callbackUrl string Optional

HTTPS URL of your endpoint to receive callback POST requests. Required to enable callback mode.

callbackSecret string Optional

Secret key for HMAC-SHA256 signature verification. Ensures callback request authenticity.

callbackMode string Optional

Callback payload mode. Enum: "full" (default), "statusOnly". "full" returns complete result data, "statusOnly" returns only task ID and status.

Response

code integer

Returns 0 for success, or a specific error code.

message string

Returns "success" or a descriptive error message.

data object

taskId string

The unique identifier for the async task.

Errors

10192Illegal param

Callback Request Headers

When DreamAPI sends a POST callback request to your configured callback URL, the following custom request headers will be attached for identity verification, event identification and deduplication.

Content-Type string Required

Fixed value: application/json. The callback request body is always in standard JSON format.

X-DreamAPI-Event string Required

Fixed event type: task.completed. Indicates the async task has finished processing (success or failure).

X-DreamAPI-TaskId string Required

Unique ID of the asynchronous task corresponding to the current callback, consistent with the taskId returned when submitting the task.

X-DreamAPI-Signature string Optional

HMAC-SHA256 signature of the callback raw payload. Format: sha256=hex_string. Only carried if callbackSecret is passed when submitting the task, used to verify request legitimacy and prevent fake callback attacks.

X-DreamAPI-Attempt integer Required

Callback delivery retry sequence number, starting from 1. Increases automatically with each retry, used for business deduplication and troubleshooting delivery failures.

Polling

The Polling API includes callback status information when callback parameters are enabled.

Task Processing (callback pending)

12345678910111213{
  "code": 0,
  "message": "success",
  "data": {
    "task": {
      "taskId": "b08337dc08d7428daa64b3d5e61b8350",
      "status": 2,
      "callback": {
        "status": "pending"
      }
    }
  }
}

Request

cURL

123456789curl -X POST 'https://api.newportai.com/api/async/video_super_resolution' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{APIKey}}' \
  -d '{
  "srcVideoUrl": "https://example.com/source.mp4",
  "callbackUrl": "https://your-service.com/callback",
  "callbackSecret": "your_secret_key",
  "callbackMode": "full"
}'

Callback Full Mode Payload

1234567891011121314151617181920{
  "code": 0,
  "message": "success",
  "data": {
    "task": {
      "taskId": "b08337dc08d7428daa64b3d5e61b8350",
      "status": 3,
      "reason": "",
      "taskType": "video_super_resolution",
      "executionTime": 17232,
      "expire": 1769586737611
    },
    "videos": [
      {
        "videoType": "mp4",
        "videoUrl": "https://dreamface-resource-aigc.oss-us-east-1.aliyuncs.com/dreamapi/o/2026-01-26/f19ec50fc7ca418aafa918f57298ce76.mp4"
      }
    ]
  }
}