Async tasks & results
Generation is asynchronous. Obtain a token, create a task and keep its task_id. Query the result or receive notifications through the account-level Webhook configured in Console. All task endpoints support notifications.
- Get a token
- Create a task and save
task_id - Query status / receive a callback
- Save result files after success
API task states
data.state | Meaning | What to do |
|---|---|---|
created | Created | Keep task_id and query again |
queueing | Queued | Wait for processing |
processing | Processing | Query again or wait for a callback |
success | Succeeded | Read url and, when available, cover_url and download promptly |
failed | Failed | Inspect the error and refund record, fix the input and decide whether to submit again |
Querying and callbacks
- Poll the task: Use the query path for the task type and pass the
task_idreturned at creation. - Receive notifications: Configure an account-level Webhook in Console for success and failure notifications. You can still query a task if the notification does not arrive.
- Handle a request timeout: Query the original
task_idbefore deciding whether to submit again.
Results and credits
- Result links: On success, read
data.urland, when available,data.cover_url. File and preview links are valid for one hour. - Expired links: Query the original
task_idagain. Keep the full signed URL when downloading. - Credits: Credits are debited after successful submission and refunded if the task fails. Check task records for the original deductions and refunds.
Webhook configuration → · Error handling →
API support:apicontact@hi3d.ai