# H3 Shared Queue — AI Agent Instructions

This site is a private MiniMax H3 reference-to-video preparation queue.
Use the queue API for reference images and prompts. Do not deploy, start, stop,
or otherwise control a GPU provider.

## Non-negotiable rules

- Never run `h3-up`, `h3-down`, Vast.ai, or RunPod commands. The human owner
  controls every action that starts or stops billing.
- Never print, log, copy, or expose `H3_SHARED_KEY`.
- A submitted or queued job does not start a GPU. Jobs wait until the owner
  manually runs `h3-up` on the authorized Mac.
- Do not queue all ready jobs unless the user explicitly asks you to do so.
- Use an absolute path for the local reference image. Accepted formats are
  JPG, PNG, and WebP, up to 15 MB.

## Preferred workflow

Download the dependency-free client from this same origin:

```bash
curl --fail --show-error \
  https://h3-shared-queue.pages.dev/h3-client.py \
  --output h3-client.py
```

Write the complete MiniMax H3 I2VA prompt to a UTF-8 text file, then submit
one ready job:

```bash
python3 h3-client.py submit /absolute/path/reference.jpg \
  --prompt-file /absolute/path/prompt.txt \
  --name descriptive-output-name \
  --profile turbo \
  --ready \
  --json
```

Report the returned job ID to the user. `--ready` means ready for a future
manual batch; it does not start billing.

If the user explicitly asks to collect all currently ready jobs into the
manual-start queue:

```bash
python3 h3-client.py run
```

This command still does not start a GPU. The human owner must run `h3-up`.
While a batch is still waiting for manual `h3-up`, repeating `run` appends newly
ready jobs to that same batch. Once rendering has started, new jobs wait for the
next batch.

After the owner starts H3, monitor and download a specific result:

```bash
python3 h3-client.py wait JOB_ID \
  --timeout 7200 \
  --output /absolute/path/result.mp4
```

List recent jobs without changing anything:

```bash
python3 h3-client.py list
```

## Authentication

The owner supplies the private shared password separately. Prefer an injected
secret environment variable named `H3_SHARED_KEY`. If it is absent, the client
asks for it through a hidden password prompt. Never place the password in a
command argument, prompt file, source file, chat message, or generated report.

## Profiles

- `turbo-draft`: cheapest four-step candidate
- `turbo`: default eight-step short-form candidate
- `draft`: non-Turbo candidate
- `balanced`: slower stability pass
- `final`: selected Natural final only
- `native`: expensive native-resolution run; use only when explicitly requested

Use `turbo` unless the user specifies another profile.

## Prompt requirements

Preserve the reference subject and describe one continuous shot in temporal
order. A production prompt should include:

```text
For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.

integrated_multimodal_description: [Shot 1] ...

overall_soundscape: ...

non_diegetic_music: ...
```

If the web prompt helper returns
`[지원되지 않는 내용 — 직접 수정 필요]`, do not silently replace the user's
intent. Keep the original, report the marker, and ask the user to revise it.
A prompt containing that marker cannot enter the ready queue.

## Raw API discovery

The client is preferred, but the authenticated API is available at:

- `POST /api/session`
- `GET` or `POST /api/jobs`
- `PATCH /api/jobs/:id`
- `POST /api/jobs/:id/ready`
- `POST /api/jobs/:id/prompt-rewrite`
- `POST /api/batches` — queue only; never starts a GPU
- `GET /api/status`
- `GET /api/jobs/:id/result`

Machine-readable discovery starts at `/llms.txt`. Human operators can use the
web interface at the site root.