GET · /api/v1/generations/{id}

Read a generation.

Returns the current status of a generation you submitted. Use this to poll until the job finishes and the output_url is ready.

Request

GET /api/v1/generations/5b91a581-ee19-4f86-9fea-bd29471d69d5 HTTP/1.1
Host: getvivix.com
Authorization: Bearer vvx_live_…

Path params

FieldTypeNotes
idstring (uuid)The generation_id returned by /api/v1/generate.

Response · pending

Every response — regardless of status — carries the same field set; only the values change. While the job is in the queue or rendering, the output fields are still null:

HTTP/1.1 200 OK
{
  "generation_id": "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":         "processing",
  "model":          "grok-imagine-image-quality",
  "output_url":     null,
  "output_urls":    null,
  "credits_used":   211,
  "duration_ms":    null,
  "created_at":     "2026-05-10T12:34:56Z",
  "completed_at":   null,
  "request_id":     "req_9f2c7a1b3d8e"
}

credits_usedis already non-null here — it's the amount reserved from your balance at submission, before we know the final cost. On most models that reserved figure is the final charge; a small number of models true it up once the job completes, so treat this value as provisional until status reaches a terminal state.

Response · completed

HTTP/1.1 200 OK
{
  "generation_id": "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":        "completed",
  "model":         "grok-imagine-image-quality",
  "output_url":    "https://getvivix.com/api/v1/output/5b91a581-ee19-4f86-9fea-bd29471d69d5/1799990000/9f3a2b71c4d80e55a1b6f204d7c983ee/0/getvivix-5b91a581.jpg",
  "output_urls":   ["https://getvivix.com/api/v1/output/5b91a581-ee19-4f86-9fea-bd29471d69d5/1799990000/9f3a2b71c4d80e55a1b6f204d7c983ee/0/getvivix-5b91a581.jpg"],
  "credits_used":  211,
  "duration_ms":   12420,
  "created_at":    "2026-05-10T12:34:56Z",
  "completed_at":  "2026-05-10T12:35:08Z",
  "request_id":    "req_9f2c7a1b3d8e"
}

output_url is the primary asset; output_urls is the full set when you requested number_results > 1 on an image model. Both are signed getvivix.com links — no Authorization header needed to fetch them, the signature in the URL itself is the credential — valid for 3 days from the moment this response is generated. Download the bytes (or re-host them yourself) before the link ages out; polling this endpoint again always mints a fresh one.

Response · failed

HTTP/1.1 200 OK
{
  "generation_id": "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":        "failed",
  "model":         "grok-imagine-image-quality",
  "output_url":    null,
  "output_urls":   null,
  "credits_used":  0,
  "duration_ms":   3180,
  "created_at":    "2026-05-10T12:34:56Z",
  "completed_at":  "2026-05-10T12:35:00Z",
  "request_id":    "req_9f2c7a1b3d8e",
  "error": {
    "code":      "model_unavailable",
    "message":   "This model is temporarily unavailable. Please try another model — your credits have been refunded.",
    "retryable": true
  }
}

Failed jobs refundthe credit charge automatically in almost every case — you're only billed for completed work. Don't guess whether to resubmit: read error.retryable. true means the identical body has a real chance of succeeding on a second try (capacity, a transient provider hiccup); falsemeans something about the request itself won't change on a retry (a blocked prompt, an unsupported setting) — retrying as-is just burns another charge for the same result.

One exception to the auto-refund: error.code: "CONTENT_POLICY_VIOLATION" means the generation rendered successfully but was flagged by our safety review after the fact — those credits are forfeited, not refunded, the same policy Studio applies. Every other failure code refunds.

Status values

StatusMeaning
pendingQueued. Will pick up within a few seconds usually.
processingActively rendering on the underlying provider.
completedDone. output_url is set.
failedErrored. credits_used = 0 in almost every case (see the refund exception above).
Recommended polling interval: 2 seconds for image, 4 seconds for video. Unlike POST /api/v1/generate — metered per your plan (240/min Pro, 420/min Pro Plus, 600/min Ultimate) — this polling endpoint carries no rate limit of its own today. Still poll like a considerate client; if you're tracking more than a handful of jobs at once, a webhook scales better than a loop per job.

Errors

Common errors — see the full error reference:

  • 401 — missing, malformed, or revoked key
  • 404 NOT_FOUND — no generation exists with that id or it belongs to a different account. Deliberately identical either way: we never confirm or deny that a generation_idyou don't own actually exists.
  • 500 INTERNAL_ERROR — rare read failure on our side; retry in a few seconds

Where to next