Manage AI jobs — status and download

Every generation creates a creative_job row. Track via GET /api/v1/creative-hub/jobs/:jobId (verified apps/backend/src/routes/api/creative-hub-generate.route.ts). Status enum: pending / processing / completed / failed. Polling pattern: client → request submitted → 202 Accepted + job_id → polls every 5-10 seconds until status = completed (or failed). Failed jobs include error_message. Completed jobs: result_urls populated + drive_folder_id + cost_cents recorded.

Who is this for

Anyone running generations. The Jobs panel is where you live during active creative work.

The 4 job states

State transitions: pending → processing → completed OR failed. No other transitions (e.g. completed doesn't go back to processing).

The Jobs panel

In Wevion UI: typically a side panel or modal showing recent generations:

• Active jobs: those in pending or processing — with spinner

• Recent completed: with preview thumbnail + download + use-in-campaign actions

• Recent failed: with error_message + retry button

Per-job card:

• Type badge (image / video / avatar / tts / composite)

• Provider name

• Submitted timestamp

• Duration (if completed)

• Cost (if completed)

• Actions: View, Download, Use in Campaign, Delete (just clears UI; doesn't delete the underlying file)

Polling pattern (client side)

When you submit a generation:

1. POST /api/v1/creative-hub/generate/image (or video / avatar / etc.)
2. Response: 202 + {job_id: "abc-123", status: "pending"}
3. Client polls: GET /api/v1/creative-hub/jobs/abc-123 every 5-10 sec
4. Responses:
   - pending → continue polling
   - processing → continue polling
   - completed → render result_urls
   - failed → show error_message

5-10 sec polling interval is sufficient. Don't poll faster (no speedup; just more load). Don't poll slower (UI feels unresponsive).

Endpoint

GET /api/v1/creative-hub/jobs/:jobId (verified).

Returns the creative_job row:

{
  id: "abc-123",
  user_id: "...",
  type: "image",
  status: "completed",
  provider: "flux_2_pro",
  prompt: "...",
  settings: {...},
  result_urls: ["https://drive.google.com/...", ...],
  error_message: null,
  cost_cents: 25,
  drive_folder_id: "...",
  metadata: {...},
  created_at: "...",
  completed_at: "..."
}

For failed jobs: result_urls empty, error_message populated.

Downloading results

Within Wevion

Click the job in the Jobs panel → preview opens → Download button.

Or navigate to the Creative Hub folder where output was stored — generated files appear there automatically.

Via API / external

Each result_urls entry is a direct URL (Drive shared link or signed S3 URL depending on storage configuration). Right-click → Save As to download.

For programmatic access: the URL works for direct GET (subject to expiry if signed).

Use-in-campaign shortcut

From the Jobs panel: completed jobs have a Use in Campaign button → opens Campaign Creator with the result file pre-selected in the creative block.

Saves a click vs Creative Hub → browse → pick.

Retrying failed jobs

In Jobs panel: failed job → Retry button. Re-submits with same params.

Common reasons to retry:

• Provider had transient error (resubmit usually succeeds)

• Content moderation rejection (need to reword prompt — retry won't help without edit)

For content moderation: edit prompt, resubmit as new (not retry).

Filtering + searching jobs

Jobs panel typically supports:

• Filter by status (active / completed / failed / all)

• Filter by type (image / video / etc.)

• Filter by date range

• Search by prompt text

For long history: filter to relevant time window or type.

Job retention

Jobs (in creative_job table) retained per workspace plan. Older jobs may be archived from the active panel but remain in the underlying table for audit + reporting.

Generated output files (in Drive) follow Drive retention — no automatic deletion unless explicit cleanup.

Cost reconciliation

Each completed job's cost_cents debits team credit balance. To reconcile:

1. Jobs panel → filter completed in month

2. Sum cost_cents across jobs

3. Should match the month's debit in /settings/team/billing

Failed jobs (cost_cents = 0) don't affect this calc.

Common mistakes

• Polling faster than 5-sec interval: no benefit, adds load

• Not polling at all: UI shows "pending" forever; refresh / re-open panel to fetch latest

• Confusing "Delete" in panel with deleting the file: panel delete just hides job; underlying file in Drive untouched

• Retrying failed jobs without diagnosing: if cause is structural (prompt, params), retry just wastes time

Common issues

• Job stuck pending > 5 min: worker queue backed up; usually self-resolves; if persistent, see ch-128

• Completed job's result_urls broken: Drive permission issue or file moved; check Drive directly

• error_message empty on failed job: rare; usually upstream provider issue; retry once

• Same prompt different cost on different submissions: pricing fluctuates per upstream provider; small variance expected

Related

• AI generation overview — the broader pipeline

• AI credits — how cost_cents charges work

• Troubleshooting — when jobs misbehave