招鲤用户2625
Async and Callbacks: Task Model, Polling, and Callbacks
输入“/”快速插入内容
Async and Callbacks: Task Model, Polling, and Callbacks
Async and Callbacks: Task Model, Polling, and Callbacks
用户2625用户2625
用户9470用户94703月19日修改
Asynchronous task model
Video and image processing jobs are asynchronous. You submit a task and receive an idProject (and often idWorks or task-specific IDs). The server processes in the background. You either poll for status or provide a callback URL to receive a notification when the job finishes.
Core concepts
Each task has two key IDs:
•
idProject (batch ID) — one submission can include multiple video URLs sharing the same idProject
•
id / idWorks (work ID) — each video URL has one work ID; use this ID when querying result
Polling
Recommended polling strategy:
•
Start with an interval of about 10 seconds; adjust after each query as needed
•
Query by idWorks for a single work item for better efficiency
•
Poll endpoint: POST /v-w-c/gateway/ve/work/status (video) or the corresponding image API
•
Pagination is supported; you can also filter by createTimeGreaterThanOrEqualTo / createTimeLessThan
Task lifecycle
Call the task status/result endpoint with the task ID. Check processStatus: processing means wait and retry; success means result URLs are in the response; failure means inspect the error and optionally retry or re-submit. A typical interval is every few seconds; avoid polling too frequently.
Callbacks
processStatus value and meaning
The table below summarizes processStatus for video tasks. For full values and semantics see the Appendix.
For image tasks, status codes are available via the enum query API (ImageTaskStatus).
processStatus value | Meaning |
< 1 | Processing |
1 | Success |
> 1 | Failure |
When creating a task, you can pass a callback URL. When the job completes, the server POSTs a payload to that URL with the task result. Your endpoint should respond quickly (e.g. 200 OK) and handle duplicate deliveries (idempotency). Verify the callback signature if the API provides one.
Callback format
•
Method: POST
•
Body: JSON, same as one item in the query result body.content (no outer msg/code wrapper)
•
Success: respond with HTTP 200 and any non-empty body; otherwise the callback is treated as failed
Retry mechanism
GhostCut retries callbacks every 30 minutes for works created within the last 24 hours whose callback failed. Keep your callback URL reachable.
Callback signature verification
For security, GhostCut sends a Callback-Sign header. It is computed with the same formula as your request sign, applied to the callback body:
Key identifiers
代码块
Callback-Sign = md5( md5(callback_body) + AppSecret )
idProject: top-level project/job ID. idWorks: work item ID within a project. processStatus: current state (e.g. processing, success, failure). Exact values and semantics are described in the Appendix and in each API reference.
Verify the signature on your side with the same formula to ensure the callback is from GhostCut.
Idempotency
Because callbacks can be retried, you may receive the same callback more than once for one work. Deduplicate by work id and ensure your logic is idempotent.