GET/api/v1/jobs/:id

Job status

Check a generation job or follow it live with SSE events.

Generating, correcting, adapting or translating is not instant: the API returns a job and the AI finishes it later. You can check its status whenever you want, listen to it live, or wait for the webhook. Requires the read permission (or any of the others).

Check the status

The status field is queued, running, succeeded, failed or canceled. When it finishes well, creativeId is the concept you can read with GET /api/v1/banners/:id and appUrl opens that concept in the app's studio. If it fails, error has a code and a message, and the credits are returned.

FieldWhat it is

id, type

The job id and its type: generate, edit, adapt or translate.

status

The job status.

creativeId, versionNo

The resulting concept and its version, once it finishes.

appUrl

Absolute link to the concept in the studio. null while it runs, if it failed, or with a test key.

error

null or the reason for the failure.

creditsCharged

Credits charged for the whole job (all sizes and locales).

createdAt, startedAt, finishedAt

Dates in ISO 8601 format.

Live events (SSE)

SSE (Server-Sent Events) is a stream of live notices over HTTP: you open the connection and the server sends you the progress.

The endpoint GET /api/v1/jobs/:id/events opens a text/event-stream stream. First it sends a status event with the current status and then, as it progresses, queued, running, progress (with step and pct) and finally succeeded or failed, and the server closes the stream.

The stream sends a heartbeat line (: ping) every 15 seconds to keep the connection alive.
It closes on its own after 5 minutes at most: reconnect or query GET /api/v1/jobs/:id.
If the job had already finished, you receive status and the stream closes.
A key without permission or a foreign id responds 401, 403 or 404 before the stream opens.

备注。 With a bm_test_ key, job_test_… ids already come as succeeded, with test: true and no credits charged.

Webhook eventsThe 13 events, all emitted today: when they fire, what the data field carries and an example of each.Get a bannerReads the spec, the current version, the pieces and the texts of a concept, or lists the concepts in your workspace.

这一页对你有帮助吗？