# Wan 3.0 Prime API

A practical Python client, MCP server, shell examples, and implementation notes for the **Argolink Wan 3.0 Prime** video API. The repository is organized around the workflows that an integration needs: text-to-video, first-frame and first/last-frame generation, reference assets, asynchronous polling, media uploads, and safe downloads.

[Argolink Wan 3.0 Prime model page →](https://argolink.io/gh-wan-3-0-prime-api) · [Argolink API docs →](https://argolink.io/gh-unified-api-docs)

> This is an integration guide. The model page is the source of truth for live availability, customer pricing, limits, and model-specific behavior.

## What is included

- `wan_api.py`: a small synchronous Python client using the public REST contract.
- `mcp_server.py`: optional MCP tools for submit, status, and the three input modes.
- `examples/`: executable `curl` workflows for submit, reference assets, uploads, polling, and download.
- `docs/api-contract.md`: endpoint, request, response, billing, and limit details.
- `docs/troubleshooting.md`: actionable handling for validation, authentication, upload, timeout, and terminal-job errors.
- `argolink/FACTS.md`: the checked Argolink model facts used by this repository.
- `argolink/VIDEO_MAPPING.md`: the mapping from the public methods to the REST fields.

## Requirements

- Python 3.9 or newer for the client.
- `requests` for the Python client.
- An Argolink API key in `ARGOLINK_API_KEY`.
- `curl`, `jq`, and `file` for the shell examples.

Install the Python dependencies in a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

The client uses `https://api.argolink.io` by default. Set `ARGOLINK_BASE_URL` only when testing against an explicitly approved compatible environment.

## Quickstart: text-to-video

```python
import os
from wan_api import WanPrimeAPI

client = WanPrimeAPI(api_key=os.environ["ARGOLINK_API_KEY"])
job = client.text_to_video(
    prompt="A paper kite crosses a quiet coastal town at golden hour, cinematic motion",
    duration=5,
    resolution="720p",
    aspect_ratio="16:9",
)
print(job["request_id"])

result = client.wait_for_completion(job["request_id"], max_wait_seconds=900)
if result["status"] == "done":
    client.download(result["request_id"], "wan-prime-result.mp4")
```

The submit response is asynchronous. Store `request_id`, poll the status endpoint, and download only after the job is `done`. Do not automatically resubmit a timed-out request: a timeout does not prove that the server did not accept the original job.

## Input modes

### Prompt only

`text_to_video()` sends a prompt with the selected duration, resolution, ratio, and soundtrack switch.

### First frame or first and last frame

`image_to_video()` accepts HTTPS image URLs. Frame workflows use `adaptive` ratio so the input frame controls the shape. The first and last images are mutually dependent: an ending frame requires a starting frame.

```python
job = client.image_to_video(
    prompt="The camera slowly pushes forward while the subject turns toward the light",
    start_image="https://example.invalid/start.jpg",
    end_image="https://example.invalid/end.jpg",
    duration=6,
)
```

### Reference assets

`reference_to_video()` accepts up to ten images, five videos, and five audio tracks, with at most twenty assets in one request. The prompt is always required. Use the mention syntax described on the model page when a prompt needs to identify an asset:

```python
job = client.reference_to_video(
    prompt="Use @Image 1 for the character and @Video 1 for the camera movement",
    reference_images=["https://example.invalid/character.jpg"],
    reference_videos=["https://example.invalid/movement.mp4"],
)
```

Reference videos have a combined duration limit, and their seconds are included in billing. Reference images and audio are accepted as inputs without adding reference-video seconds to the bill. Confirm the current model page before relying on a limit in a long-running production workflow.

## Shell workflow

```bash
export ARGOLINK_API_KEY='your-key'
./examples/submit-text.sh "A slow dolly shot through a rain-lit market"
./examples/poll-and-download.sh REQUEST_ID ./result.mp4
```

The examples print request IDs and status values, never API keys. Read `examples/README.md` before adapting them for CI.

## MCP server

Install the optional MCP dependency and run the server over stdio:

```bash
python -m pip install 'mcp[cli]>=1.0'
python mcp_server.py
```

The server exposes four narrow tools: text submit, frame submit, reference submit, and status lookup. It reads `ARGOLINK_API_KEY` from the process environment; it does not accept keys in tool arguments or persist them.

## API behavior that matters in production

- Submit with `POST /v1/videos/generations`; the normal response is HTTP 202.
- Poll with `GET /v1/videos/{request_id}` until `done`, `failed`, or `expired`.
- Fetch the generated bytes with `GET /v1/videos/{request_id}/content` after completion.
- Upload large local assets through `POST /v1/media/uploads`, then PUT bytes to the returned signed URL with the exact content type.
- Completed output seconds and reference-video seconds determine billing. Failed and rejected jobs are not billed according to the model page.
- The model accepts one output per request. Unsupported options should be omitted instead of guessed; the API returns a validation error when a field is not supported.

For the complete field mapping, error shapes, and current limits, see [`docs/api-contract.md`](docs/api-contract.md) and [`docs/troubleshooting.md`](docs/troubleshooting.md).

## License and security

This repository is released under the MIT License. See [`SECURITY.md`](SECURITY.md) for the reporting path and key-handling rules. Never commit `.env`, API keys, signed upload URLs, generated media, or production responses.