API Reference
Integration Guides

Async Jobs

Most generation routes return 202 first. Poll request status or subscribe to webhooks.

When to expect async behavior

  • Most music generation, track generation, track editing, TTS, dubbing, and longer STT jobs return 202 Accepted.
  • POST/v1/music/lyrics/extend completes synchronously.
  • POST/v1/sound-effects/generate usually completes synchronously on the success path.
  • POST/v1/speech/speech-to-text can return either 200 or 202 depending on the audio path and job length.

Rule of thumb

If a route returns a request_id, treat it as an asynchronous workflow and build completion around polling or webhooks.

The accepted response

Most async endpoints return a compact accepted envelope immediately. Persist the request_id on your side and treat it as the durable handle for the job.

Typical 202 responsejson
{
  "success": true,
  "data": {
    "request_id": "590b41ed-bf0f-42cf-bad9-32568c09475a",
    "status": "accepted",
    "operation": "music.song.generate",
    "event": "music.song.generate",
    "message": "Request accepted and processing started"
  }
}

Polling with /v1/requests

GET/v1/requests/:requestId is the canonical cross-service polling route. It returns ownership-checked status, timing metadata, and a result URL once available.

GET/v1/requests/:requestId
Auth: API keyBilling: FreeBehavior: Canonical async polling routeScopes: analytics:read
Completed request responsejson
GET /v1/requests/590b41ed-bf0f-42cf-bad9-32568c09475a

{
  "success": true,
  "data": {
    "request_id": "590b41ed-bf0f-42cf-bad9-32568c09475a",
    "status": "completed",
    "service_category": "music",
    "service_operation": "song.generate",
    "credits_used": 1,
    "credits_estimated": 1,
    "result_url": "https://cdn.wubble.ai/api-generations/...",
    "error_message": null,
    "estimated_seconds": 75,
    "created_at": "2026-05-12T09:40:00.000Z",
    "updated_at": "2026-05-12T09:41:15.000Z",
    "completed_at": "2026-05-12T09:41:15.000Z"
  }
}

Polling cadence

Start with a short delay, then back off. For most client applications, polling every 2 to 5 seconds is enough until completion.

Speech-specific status route

Speech workflows also expose GET/v1/speech/status/:requestId. Use it when you want speech-specific status semantics around TTS, STT, or dubbing.

GET/v1/speech/status/:requestId
Auth: API keyBilling: FreeBehavior: Speech-specific status readScopes: analytics:read
Speech status while processingjson
GET /v1/speech/status/590b41ed-bf0f-42cf-bad9-32568c09475a

// 202 while still processing
{
  "success": true,
  "data": {
    "request_id": "590b41ed-bf0f-42cf-bad9-32568c09475a",
    "status": "processing",
    "age_minutes": 1
  }
}

Choose your completion strategy

Polling

Best for server-side jobs and smaller integrations. Keep your own timeout and stop when status reaches completed or failed.

Webhooks

Better for production pipelines. Let Wubble push terminal events to your HTTPS receiver instead of holding clients open.

Failure handling

Failed jobs keep the request record. Read error_message and expose the reason clearly to your own operators.

Result access

Completed responses typically include a CDN URL. Do not assume the original POST response will contain the final media asset.

Was this page helpful?
Previous
WebhooksNext