# Resume an existing video API task, then save its output

This is a Node.js 24 technical recipe for MiniMax H3’s public API. It resumes an **existing task ID**; it never submits a generation. The bundled evidence is an executed **localhost fixture**, not a production generation, provider quality test, or confirmation of current live API availability.

## Audited contract

Source commit: `a4818c0862ec04ac75e871ab114bcb5fa3152550`.

- `src/app/api/v1/tasks/[id]/route.ts`: `GET /api/v1/tasks/{id}`, Bearer authentication, API-owner and `public_api_v1` task scope, ID validation, 404 ownership/not-found handling.
- `src/shared/services/public-api.ts`: the response is the task object itself, without a `data` envelope. Public statuses are `processing`, `completed`, and `failed`; canceled internal tasks map to `failed`. A completed result is in `output.video_url`. The serializer reports a missing completed output as `failed`.
- `src/shared/lib/public-api-contract.ts`: the rate limit is 30 requests per 60 seconds; 429 carries a `Retry-After` header. This sample uses a five-second normal polling interval and bounded retries.

A task created by the browser may be outside the public API task scope. A 404 is a reason to check the task ID and owner, not to automatically submit a replacement paid task. A query may refresh the existing task’s state; this client does not create tasks.

## 1. Run the reproducible fixture first

Download `client.mjs` and `run-fixture.mjs` into one folder, then run:

```sh
node --version
node run-fixture.mjs
```

The fixture binds only `127.0.0.1` on a temporary port, uses a fake credential, and closes its server and removes temporary output in `finally`. It writes `execution-receipt.json`. The recorded run passed 24 scenarios on Node v24.14.0. No production API request or paid task was made. The synthetic media is 64 bytes with an MP4 `ftyp` prefix; it is **not a playable or decoded generated video**.

## 2. Prepare a known task and its owner’s API key

Use a task ID already returned by the public API. Keep the API key in the process environment as `SEEDANCE_API_KEY`; never put it in the command arguments, source file, or downloaded checkpoint. Run this client on a machine you control, not in browser JavaScript. The client only sends the key to `https://minimaxh3.studio/api/v1/tasks/{id}`.

## 3. Resume with an explicit output folder

```sh
node client.mjs --task YOUR_EXISTING_API_TASK_ID --out ./saved-video
```

Do not paste a real key into the command. This command assumes `SEEDANCE_API_KEY` is already set securely. The output filename is the validated task ID plus `.mp4`. The client saves a small checkpoint with the task ID and status; it does not save the key, raw API response, or signed media URL. Re-running the same command continues querying the same task. If a completed local file exists, its recorded size and SHA-256 must match before reuse.

## 4. Allow only the actual managed output origin

The default media allowlist is `https://minimaxh3.studio`. If the returned managed delivery URL uses another origin, verify that exact HTTPS origin against your task response and storage configuration, then allow it explicitly:

```sh
node client.mjs --task YOUR_EXISTING_API_TASK_ID --out ./saved-video --media-origin https://YOUR_VERIFIED_MEDIA_HOST
```

The API key is never forwarded to the media host. Redirects, URL user information, unexpected media origins, and non-MP4 Content-Type are refused. This is an explicit origin allowlist, not a claim that every URL on an allowed origin is a safe or valid video. An allowed signed delivery URL can contain a query string; it is used only in memory.

## 5. Bound polling and verify the saved bytes

The defaults are ten minutes total, 120 task requests, 30 seconds per request, five seconds between processing responses, and 256 MiB maximum media bytes. 429 and 503 retry within those bounds; numeric or HTTP-date `Retry-After` is capped at 60 seconds. 401/404 and `failed` exit without a new task. A stalled stream is bounded by the request timeout.

```sh
node client.mjs --task YOUR_EXISTING_API_TASK_ID --out ./saved-video --timeout-ms 300000 --max-bytes 52428800
```

The client streams into an exclusive temporary file, checks size/MIME/MP4 prefix, computes SHA-256, and publishes without overwriting an existing destination. Add `--sha256 YOUR_TRUSTED_64_CHARACTER_LOWERCASE_SHA256` only when an independently trusted checksum is available. A checksum calculated by this client proves local byte identity; it does not prove provider authenticity, decode quality, or semantic correctness. Play and inspect a real downloaded video separately.

## 6. Read errors before resuming

| Symptom | Next action |
|---|---|
| `not_found` or `unauthorized` | Check task ID, public API origin, API key owner, and key permissions. Do not generate a replacement automatically. |
| `poll_limit_exceeded` / `deadline_exceeded` | Keep the checkpoint and retry the same existing task after checking service state. |
| `task_failed_*` | Review the actual task error and billing status separately. This client does not promise or execute a refund. |
| `unapproved_output_url` | Verify the managed media origin before changing the allowlist. |
| `download_too_large`, `checksum_mismatch`, or `invalid_mp4_prefix` | Inspect expected size/format and trusted checksum. Partial media files are cleaned up. |
| `output_exists` | Inspect the existing file/checkpoint; choose a fresh folder if it is unrelated. The client refuses overwrite. |

## Acceptance checks and limits

- Fixture traffic contains only GET requests to localhost; media requests have no Authorization header.
- The checkpoint identifies the original task and contains no key or delivery URL.
- Completion produces a file with matching recorded byte count and SHA-256.
- Failure, owner mismatch, rate limit, timeout, unsafe path/symlink, unexpected origin, redirect, size, and hash errors do not submit a new task.
- The executed fixture does not validate live credentials, live task visibility, provider completion, video decoding, generation quality, billing settlement/refunds, or search traffic.

Existing keyword evidence supports an API integration topic family; no search volume is claimed for this particular recipe slug.