TranscriptionJob

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Transcription request id (UUID)."
    },
    "video_id": {
      "type": "string",
      "description": "YouTube video id (11 characters)."
    },
    "state": {
      "type": "string",
      "enum": [
        "pending",
        "ready",
        "failed",
        "refunded"
      ],
      "description": "Coarse outcome: pending until the Premium transcript is servable (ready), the job failed, or it was refunded."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "downloading",
        "transcribing",
        "analyzing",
        "complete",
        "failed",
        "refund_pending",
        "refunded"
      ],
      "description": "Request status. Values: queued (accepted; audio download not started), downloading (fetching the video audio), transcribing (premium speech-to-text is running), analyzing (entity/commercial analysis is running), complete (premium transcript is servable via GET /v1/transcripts/{video_id}), failed (rejected intent, or a legacy request needing accounting review), refund_pending (refund transaction must still complete), refunded (terminal failure; the charge was returned and the unlock this request granted was revoked)."
    },
    "stage": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "queued",
        "transcribing",
        "analyzing",
        null
      ],
      "description": "User-facing stage: downloading folds into transcribing. Values: queued (waiting to start), transcribing (downloading or transcribing), analyzing (analysis running). Null for terminal statuses and refund_pending."
    },
    "charge": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string",
          "enum": [
            "credits"
          ]
        },
        "amount": {
          "type": "number",
          "description": "Credits this job charged. 0 when a prior unlock made it free."
        },
        "from": {
          "type": "string",
          "enum": [
            "included",
            "on_demand",
            "mixed"
          ],
          "description": "Where the credits came from. included is the plan's credits, on_demand is the on-demand budget, mixed is both. Present once the job is funded."
        }
      },
      "required": [
        "unit",
        "amount"
      ],
      "description": "What the job charged. Absent only on legacy requests."
    },
    "eta_seconds": {
      "type": "integer",
      "description": "Estimated seconds until completion, re-derived from live pipeline telemetry on every poll. Only present while the request is in flight; absent on refund_pending, which has no completion ETA."
    },
    "next_poll_seconds": {
      "type": "integer",
      "description": "Seconds to sleep before the next poll (also sent as the Retry-After header). Only present while the request is in flight."
    },
    "error": {
      "type": "string",
      "description": "Failure reason. Only present when state is failed or refunded, or status is refund_pending."
    },
    "refunded": {
      "type": "boolean",
      "description": "True when the charge was returned. Only present when state is failed or refunded, or status is refund_pending (false until the refund lands)."
    },
    "created_at": {
      "type": "string",
      "description": "When the request was submitted."
    },
    "completed_at": {
      "type": "string",
      "description": "When the request reached a terminal status. Absent while in flight."
    },
    "status_url": {
      "type": "string",
      "description": "Absolute URL to read again for this job: GET /v1/transcripts/{video_id}?quality=premium, which answers 202 while it transcribes, 200 ready once it is done, and 200 failed if it failed."
    }
  },
  "required": [
    "id",
    "video_id",
    "state",
    "status",
    "stage",
    "created_at",
    "status_url"
  ],
  "description": "A Premium transcript job with its processing state, charge and URL for reading the transcript again."
}