Converting Bytes You Already Have

GET /v1/media/convert takes exactly one input: url. There is no multipart upload, no base64 parameter, and no request body on the route at all (apis/media/app/routers/media.py, convert_media). If your file is a user upload sitting in a temp directory, you cannot hand it to the API directly.

This page is the practical answer to "so what do I do?" — the patterns that work, what each one costs, and the exact behaviour of the fetch layer you are going through.

The endpoint contract itself is in Media Convert Reference; the format matrix is in Conversion Matrix.

Availability

/v1/media/convert is written but not yet deployed, and the Convert-service equivalent (/v1/convert/media) is not currently mounted either. Treat this as the contract to design against, and verify against a live host before shipping.

Why there is no upload path

The handler is a single streaming transcoder: fetch → convert_bytes → StreamingResponse. Adding an upload would mean buffering an arbitrary multipart body in memory before the transcode, which is exactly the thing the streaming design avoids. The URL-only contract keeps the request cheap and the response a pure byte stream.

Consequence: the API never sees bytes you cannot address by URL.

Upload to your own bucket, generate a presigned GET that expires in minutes, pass it in url, and delete the object when the call returns.

import boto3, requests, uuid

s3 = boto3.client("s3")
BUCKET = "my-convert-staging"

def convert_upload(path, source_format, target_format, api_key):
    key = f"in/{uuid.uuid4().hex}.{source_format}"
    s3.upload_file(path, BUCKET, key)
    try:
        url = s3.generate_presigned_url(
            "get_object", Params={"Bucket": BUCKET, "Key": key}, ExpiresIn=300,
        )
        return requests.get(
            "https://media.toolkitapi.io/v1/media/convert",
            headers={"X-API-Key": api_key},
            params={"url": url,
                    "source_format": source_format,
                    "target_format": target_format},
            stream=True,
            timeout=600,          # must exceed the server's fetch+transcode time
        )
    finally:
        s3.delete_object(Bucket=BUCKET, Key=key)

Why this is the best option: no public exposure of the file, no need for the source to be reachable by hostname, and the object disappears by construction. The API's SSRF filter resolves the bucket host, which is a normal public endpoint — it never sees your application hostname.

Delete before you read the response

The finally block above deletes the object on the way out. If you return a stream=True response and delete in finally, the delete happens as the function returns — while the server may still be downloading from the URL. Either read the body inside the try, or delete after the stream completes. The correct shape is: download the converted bytes into memory or a file first, then delete.

Corrected ordering:

try:
    url = s3.generate_presigned_url(
        "get_object", Params={"Bucket": BUCKET, "Key": key}, ExpiresIn=300,
    )
    with requests.get(CONVERT_URL, headers={"X-API-Key": api_key},
                      params={"url": url, "source_format": source_format,
                              "target_format": target_format},
                      stream=True, timeout=600) as r:
        r.raise_for_status()
        with open(out_path, "wb") as fh:
            for chunk in r.iter_content(64 * 1024):
                fh.write(chunk)
finally:
    s3.delete_object(Bucket=BUCKET, Key=key)

Pattern 2 — public object URL

If the file is already in a public bucket (or behind a CDN), just pass that URL. Cheapest option, no signing, no lifecycle management — but the source is world-readable, so this only suits non-sensitive media.

curl -sS "https://media.toolkitapi.io/v1/media/convert" \
  -H "X-API-Key: $MEDIA_API_KEY" \
  --get \
  --data-urlencode "url=https://cdn.example.com/clips/demo.mp4" \
  --data-urlencode "source_format=mp4" \
  --data-urlencode "target_format=mp3" \
  -o demo.mp3 -D headers.txt

Note --get --data-urlencode: a raw ?url=https://...&source_format=... breaks at the & inside the URL.

Pattern 3 — your own streaming endpoint

If you cannot write to object storage at all, expose a one-time download route on your own service and pass its URL. The file becomes publicly addressable for the duration of the call, so gate it with an unguessable token that is single-use and expires in minutes.

// Your side: mint a one-time URL for a local file.
app.get("/tmp/:token", async (req, res) => {
  const entry = pending.get(req.params.token);
  if (!entry || entry.used || Date.now() > entry.expiresAt) {
    return res.status(410).json({ error: "expired" });
  }
  entry.used = true;                       // single use
  res.setHeader("Content-Type", "application/octet-stream");
  createReadStream(entry.path).pipe(res);
});

Downside: the API's fetch now depends on your service being reachable from the internet within the 60 s timeout, and any hiccup in your TLS/uptime becomes a 502 you cannot distinguish from a real network failure.

Is base64 an option? No.

There is no image or data parameter on this route, and data: URLs are explicitly blocked by the scheme check. Base64 input is only supported by the decode endpoints of the Barcode toolkit, not by media conversion.

The fetch layer, precisely

You are trusting fetch_url_content() with your URL, so know what it does (apis/media/app/services/fetch.py):

Setting Value Effect
Allowed schemes http, https file, ftp, gopher, data, javascript rejected → 400 Unsupported URL scheme
Hostname required yes 400 URL must include a hostname
Private/loopback/reserved/link-local blocked Resolved via getaddrinfo and checked with is_private/is_loopback/is_reserved/is_link_local → 400 URLs pointing to private/internal networks are not allowed
Unresolvable host blocked (fail closed) Same 400 — a typo looks like a policy rejection
Redirects followed, max 5 More than 5 → fetch error → 502
Timeout 60 s total Exceeded → 502 Failed to download source file
Max download 100 MB Exceeded → 400 Downloaded content exceeds maximum size of 100 MB
TLS verification on (ssl.create_default_context()) Self-signed certs fail → 502

Two contrasts with the Convert service worth internalising if you use both: here the cap is 100 MB and the timeout 60 s (Convert's media route uses 10 MB / 15 s), and this filter checks all resolved addresses (getaddrinfo, IPv6 included) rather than gethostbyname.

The oversize check is after the download

len(resp.content) > MAX_DOWNLOAD_SIZE runs after the whole body is buffered. A 3 GB file is fully pulled into memory before the 400 is raised. Nothing protects the service's memory but the ASGI server's own request limits. Do not point this endpoint at a URL whose size you do not control.

Also note the asymmetry: oversize is a 400 (a ValueError raised after the fetch), while any non-2xx from the source (resp.raise_for_status()) is caught by the generic handler and surfaces as 502 Failed to download source file — you never see the upstream status.

The transcode is off the event loop, but not free

result = await asyncio.to_thread(convert_bytes, data, src, tgt)

to_thread keeps the ASGI event loop responsive, which is good, but FFmpeg still occupies a thread and CPU for the duration. There is no queue, no concurrency limit, and no per-request deadline on the transcode itself — the only bound is the HTTP timeout of whatever proxy sits in front of the service.

Implications for clients:

  • Your read timeout must cover download + transcode + streaming. A 60 s client timeout on a 5-minute video is a client bug, not a server error.
  • There is no progress signal: the whole output is produced before the first byte is sent, so a long transcode looks like a stalled connection.
  • Concurrent long conversions compete for CPU. If you batch, stagger submissions.

What you get back

StreamingResponse(io.BytesIO(result), media_type=MEDIA_TYPES[tgt], headers={"Content-Disposition": 'attachment; filename="converted.<tgt>"'}).

  • The body is served from a completed in-memory buffer — not a true incremental stream — so Content-Length may be absent under chunked transfer.
  • Content type is a fixed lookup keyed by target extension (MEDIA_TYPES in _shared.py), falling back to application/octet-stream for unknown targets.
  • The filename is always converted.<target>; your source filename is not preserved.

Decision guide

Your situation Use
File already in public CDN/bucket Pattern 2 — pass the URL
File in a private bucket Pattern 1 — presigned URL, delete after download
Bytes in memory, no storage available Pattern 3 — one-time streaming endpoint on your own host
Bytes in memory, and you need it now, once Convert locally with FFmpeg; the round-trip through object storage costs more than the API call saves
You need chunked/resumable uploads Not supported — this is the wrong API for the job