Sume media tools: which answer 200 and which answer 202 by default

Sume's editing endpoints do not share one default. POST /v1/video-inspect defaults to mode: sync, so you usually get a 200 with the finished result; trim, filter, compose and audio detach default to async and return a job to poll; and POST /v1/video-frames always returns 202 because it pins async. If your client assumes one pattern for all of them, one of these will surprise you.

Each statement below comes from the matching page in Sume's docs: video inspect, video trim, video filter, video frames, timeline compose and audio detach.

What is the default for each tool?

Every one of these accepts the usual communication fields mode, webhook_url and wait_timeout_seconds, except where noted. Sync waits up to 30 seconds.

Why does video-inspect default to sync?

Inspect is usually the quick step in a chain: probe plus up to 24 stills, and an optional transcript. Waiting for the answer in one round trip suits that. The handler waits up to 30 seconds and answers 200 with the finished inspect, or 202 with a queued job. So a sync default is a hint about speed, not a guarantee: a long clip or a transcript request may still come back as 202, and your code must handle both.

The docs also note there is no GET wrapper for inspect on MCP. If the submit returns 202, poll with jobs_wait and then jobs_result.

What does sync mode do on the encode tools?

For trim, filter and compose, passing mode: "sync" waits up to 30 seconds for a 200 finished job, or you get 202 and poll. These are ffmpeg re-encodes on a worker, so short clips may finish inside the window and long ones will not. Do not read a 202 on a sync request as a failure; it is the normal fall-through.

curl -X POST https://api.sume.com/v1/video-trim \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trim-sync-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "start": 2,
    "duration": 8,
    "mode": "sync"
  }'
# 200: finished job with video_url. 202: poll GET /v1/jobs/<request_id>/status

What about video-frames?

The frames docs say submit is always 202 because the route pins communicationMode: "async"; do not send mode: "sync" expecting a 200. The resource id is the job id, so poll GET /v1/video-frames/:id until resource_status is ready, or use GET /v1/jobs/:id/status. Video frames is unbilled, so polling it costs nothing either.

A client that treats 202 as an error for any media call will break here, and a client that treats 200 as guaranteed will break on inspect. Handle both status codes everywhere.

Which pattern should your client use?

Use one code path: submit with an Idempotency-Key, branch on 200 versus 202, and poll the job envelope when you get 202. For batch work, prefer mode: "webhook" with a webhook_url so you are told when jobs finish; the jobs and results page covers both. For an agent over MCP, jobs_wait slices the wait. Sume's docs state the defaults above, but defaults can change, so send mode explicitly in code you do not want to revisit.

What status codes should you handle?

Plan for four outcomes on any media call: a 200 with a finished result, a 202 with a job to poll, a 4xx with a stable error code such as video_trim_range_conflict, and a later job failure with its own typed error. Stable codes are meant for branching, so match on the code and not on message text.

Reads are cheap. Polling GET /v1/jobs/:id/status does not bill anything, and when the status says the result is ready, GET /v1/jobs/:id/result returns a kind field such as video_trim, video_filter, audio_detach or timeline_compose. Use that field to pick the parser rather than assuming the shape from the endpoint you called.