Tasks and webhooks

Media generation is asynchronous. POST /api/v1/generation/create returns a taskId; retrieve the terminal result by polling or webhook.

Status values

Status	Terminal	Meaning
`not_started`	No	Queued and not yet dispatched.
`processing`	No	Running at a provider or processing returned media.
`finished`	Yes	Success. Read `files` and/or `output`.
`failed`	Yes	Failure. Read `errorMessage`; the charge is refunded.
`expired`	Yes	Retained task details are no longer available.

Polling


curl https://api.api-stock.com/api/v1/task/status/$TASK_ID \
  -H "Authorization: Bearer $API_STOCK_KEY"


{
  "code": 200,
  "data": {
    "taskId": "019ca881-9503-7270-a560-f00fc2b15785",
    "status": "finished",
    "files": [{ "fileUrl": "https://storage.api-stock.com/result.mp4", "fileType": "video" }],
    "output": null,
    "createdTime": "2026-08-22T12:00:00.000Z",
    "errorMessage": null
  }
}

Check the status rather than the presence of files: some actions finish with structured data only in output. Poll with backoff as described in Errors and limits.

Webhooks

Add a public HTTPS URL beside model and input:


{
  "model": "veo3.1-fast",
  "input": { "prompt": "A waterfall at sunrise" },
  "webhook": "https://example.com/hooks/api-stock/long-random-secret"
}

API Stock sends a JSON POST after the task becomes finished or failed. The body matches the status response. Return a 2xx quickly and process expensive work after acknowledging delivery.

Deliveries are retried with exponential backoff, but there is no self-service replay. Keep polling as a slow reconciliation path.

Security: webhook requests currently have no signature header. Put a long random secret in the URL, validate task ownership, and fetch its status before performing sensitive actions.