Transcribe

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ffmpeg-micro-com/json-schema/ffmpeg-micro-com-transcribe-schema.json",
  "title": "Transcribe",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ffmpeg-micro-com-openapi.yaml#/components/schemas/Transcribe",
  "type": "object",
  "required": [
    "id",
    "status",
    "media_url",
    "output_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "$ref": "#/$defs/TranscodeStatus"
    },
    "job_type": {
      "type": "string",
      "enum": [
        "transcribe"
      ]
    },
    "media_url": {
      "type": "string",
      "description": "GCS URL of the source audio/video (echoed from the request)"
    },
    "input_url": {
      "type": "string",
      "description": "Same value as `media_url` (legacy field name on reads)"
    },
    "output_format": {
      "type": "string",
      "enum": [
        "srt"
      ],
      "description": "Always `srt` for transcribe jobs"
    },
    "output_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "`gs://` URL of the generated SRT once `status` is `completed`. Use `/v1/transcribe/{id}/download` to obtain a signed HTTPS URL.\n"
    },
    "error_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Populated when status is `failed` or `canceled` (\"Job canceled by user\")"
    },
    "error_category": {
      "type": "string",
      "enum": [
        "processing_limit",
        "file_size",
        "quota",
        "upload",
        "storage",
        "validation",
        "processing",
        "transient",
        "unknown"
      ],
      "description": "Machine classification derived from error_message (generated column). Only meaningful when status is `failed`; jobs with no error carry `unknown`, never null.\n"
    },
    "duration_seconds": {
      "type": [
        "number",
        "null"
      ],
      "description": "Duration of the source media (drives billing — input minutes)"
    },
    "billable_minutes": {
      "type": [
        "number",
        "null"
      ],
      "description": "Billable minutes, metered per second on input duration (a 19-second job bills 0.3167). Not an integer.\n"
    },
    "processing_time_seconds": {
      "type": [
        "number",
        "null"
      ],
      "description": "Wall-clock processing time measured by the toolkit; null until completed"
    },
    "queue_position": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Jobs waiting in the job's toolkit lane at acceptance, this one included: the accepting worker's queue length right after this job was enqueued, so 1 means it was next in line. Set once at acceptance and never updated: a rough \"how far back was I\", not a live counter. Once `started_at` is set the job is no longer waiting, whatever this says. Null on jobs accepted before the field existed, or when the toolkit's accept response carried no queue length.\n"
    },
    "lane": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "short",
        "long",
        "heavy",
        null
      ],
      "description": "The processing lane the job runs in. Jobs with many large inputs (more than five 4K frames' worth of pixels in total) go to `heavy`, a service with more memory. Otherwise, inputs longer than two minutes (by probed length or requested output span) go to `long`; everything else is `short`. Each lane is a separate service, so nothing in one can delay a job in another. Null on jobs accepted before lanes existed.\n"
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the toolkit began executing the job. Set as soon as encoding starts, so null means the job is still waiting in its lane and non-null with status `processing` means it is encoding now. If that start signal was missed, it is filled from the completion or failure report. `started_at - created_at` is submission-to-start and includes the gateway's own download and probe before dispatch, so it is an upper bound on queue wait, not the wait itself.\n"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "user_id": {
      "type": "string",
      "description": "Internal user identifier resolved from API key"
    }
  },
  "$defs": {
    "TranscodeStatus": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed",
        "canceled"
      ],
      "description": "Job lifecycle: `pending` (created, awaiting pickup) → `processing` → `completed` | `failed`; a user cancellation sets `canceled` (US spelling). Note there is no `queued` status — new jobs start as `pending`.\n"
    }
  }
}