Get a transcode

get/v1/transcodes/{id}

Request

  • Base URL: https://api.ffmpeg-micro.com
  • URL: https://api.ffmpeg-micro.com/v1/transcodes/{id}
  • Auth: HTTP bearer

Path parameters

idstring uuid required

Response

OK

idstring uuid required
status'pending' | 'processing' | 'completed' | 'failed' | 'canceled' required

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.

output_formatstring required

Output format as submitted — the value is stored verbatim, so a job created with jpg or MP4 reads back exactly that way (validation is case/alias-insensitive; canonical values are mp4, webm, mov, avi, mp3, m4a, aac, wav, ogg, opus, flac, jpeg, png, gif, webp). Rows with job_type: transcribe carry srt.

job_type'transcode' | 'transcribe'

Discriminator — transcode and transcribe jobs share this resource shape and both appear in GET /v1/transcodes listings (there is no job_type filter). Transcribe rows additionally carry media_url.

billable_minutesnumber

Billable minutes, metered per second on input duration (a 19-second job bills 0.3167). Not an integer.

duration_secondsnumber

While the job is pending/processing: the billable input span (sum of input durations after trim options such as -ss/-t). Once completed: replaced by the measured duration of the OUTPUT file, which can differ from the input span (e.g. loops run longer). Billing always uses the input-side value.

processing_time_secondsnumber nullable

Wall-clock processing time measured by the toolkit; null until completed

queue_positioninteger nullable

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.

lane'short' | 'long' | 'heavy' | 'null' nullable

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.

started_atstring date-time nullable

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.

error_messagestring nullable

Populated when status is failed, and also on user cancellation (canceled jobs carry "Job canceled by user") — do not treat non-null error_message alone as job failure.

error_category'processing_limit' | 'file_size' | 'quota' | 'upload' | 'storage' | 'validation' | 'processing' | 'transient' | 'unknown'

Machine classification derived from error_message (generated column). Only meaningful when status is failed; jobs with no error carry unknown, never null. processing_limit is reserved for a job stopped at a per-job processing ceiling; no deployed release emits it yet (the ceiling ships separately).

completed_atstring date-time nullable

Set on successful completion only — failed jobs keep this null

output_urlstring nullable

Populated when status = completed

created_atstring date-time required
updated_atstring date-time
user_idstring

Internal user identifier resolved from API key

input_urlstring

[DEPRECATED] Use inputs array instead

Example response

{
  "id": "b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3",
  "billable_minutes": 2.25,
  "duration_seconds": 135,
  "queue_position": 3,
  "ffmpeg_options": {
    "options": [
      {
        "option": "-c:v"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.