How to use the Hy-Nomas API

The Hy-Nomas API on Windflow runs Hy-Nomas, Tencent Hunyuan's open world model, as a streaming session. A text prompt opens a world at 832 × 480 and 24 fps; held keys move and turn the view, and later prompts change what happens in the same place. The model builds the world two seconds at a time, each segment continuing from the ones before it, so keys and prompts take effect from the next segment. There is no seed image.

Hy-Nomas is offered over the WebSocket and LiveKit transports; the code below uses WebSocket. The weights are open under Apache-2.0, and the directory entry lists the sources for running it yourself.

Start from something runnable

You need an approved Windflow account and an API key that begins with wf_live_ (request access). Requests go to https://api.windflow.online.

1. Check the key (server). The response lists this model's commands, messages and limitations.

curl https://api.windflow.online/v1/models/hy-nomas \
  -H "Authorization: Bearer $WINDFLOW_API_KEY"

2. Mint a browser token (server). The account key never reaches the browser.

// For example app/api/windflow-token/route.ts. Authenticate your own user first.
export async function POST() {
  const res = await fetch("https://api.windflow.online/v1/tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WINDFLOW_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ model: "hy-nomas", max_sessions: 1 }),
  });
  return Response.json(await res.json(), { status: res.status });
}

The token is bound to this model (another model gets 403 model_mismatch) and can create one session. Read expires_at from the response instead of assuming a lifetime.

3. Open the session and draw frames (browser). Save this as windflow-session.js. It is the same file the Helios guide walks through line by line.

// windflow-session.js: plain fetch and WebSocket, no dependencies
const API = "https://api.windflow.online";

export async function call(path, jwt, body) {
  const res = await fetch(API + path, {
    method: body ? "POST" : "GET",
    headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" },
    body: body && JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.error.message), data.error, { status: res.status });
  return data;
}

export function openSession(model, canvas, onMessage = () => {}) {
  const ctx = canvas.getContext("2d");
  let session, ws, closed = false, released = false;
  let painting = Promise.resolve();

  const paint = async (bytes) => {
    const frame = await createImageBitmap(new Blob([bytes], { type: "image/jpeg" }));
    if (canvas.width !== frame.width) Object.assign(canvas, { width: frame.width, height: frame.height });
    ctx.drawImage(frame, 0, 0);
    frame.close();
  };

  const release = () => {
    closed = true;
    ws?.close();
    if (!session || released) return;
    released = true;
    fetch(`${API}/v1/sessions/${session.session_id}`, {
      method: "POST",
      keepalive: true, // still sent while the page unloads
      headers: { Authorization: `Bearer ${session.jwt}`, "Content-Type": "application/json" },
      body: JSON.stringify({ action: "detach", connection_id: session.connection_id, release: true }),
    });
  };

  const ready = (async () => {
    const { jwt } = await (await fetch("/api/windflow-token", { method: "POST" })).json();
    session = await call("/v1/sessions", jwt, { model, transport: "ws-h264" });
    while (session.status === "queued" && !closed) {
      await new Promise((resolve) => setTimeout(resolve, 2000));
      const poll = await call(`/v1/sessions/${session.session_id}`, session.jwt);
      onMessage({ type: "queued", position: poll.queue_position });
      if (poll.status !== "queued") {
        session = await call("/v1/sessions", session.jwt, { model, session_id: session.session_id, transport: "ws-h264" });
      }
    }
    const offer = session.transport.offers.find((o) => o.kind === "ws-h264");
    if (closed || !offer) throw new Error(closed ? "released" : `no stream offer (status ${session.status})`);
    const url = new URL(offer.relay_path, API);
    url.protocol = "wss:";
    ws = new WebSocket(url);
    ws.binaryType = "arraybuffer";
    return new Promise((resolve, reject) => {
      ws.onopen = () => {
        ws.send(JSON.stringify({ type: "authenticate", token: offer.launch_token }));
        ws.send(JSON.stringify({ type: "client_hello", codecs: ["jpeg"] }));
      };
      ws.onmessage = ({ data }) => {
        if (typeof data !== "string") {
          painting = painting.then(() => paint(data)).catch(console.warn);
          return;
        }
        const msg = JSON.parse(data);
        if (msg.type === "worker_ready") resolve(msg);
        if (msg.type === "failed") reject(new Error(msg.message ?? msg.error));
        onMessage(msg);
      };
      ws.onclose = (event) => {
        onMessage({ type: "socket_closed", code: event.code });
        reject(new Error(`socket closed (${event.code})`));
      };
    });
  })();
  ready.catch(release); // a failed start must not leave a session running

  return {
    ready,
    release,
    get session() { return session; },
    get socket() { return ws; },
    command: (type, fields = {}) =>
      call(`/v1/sessions/${session.session_id}/commands`, session.jwt, { command: { type, ...fields } }),
    upload: async (file) => {
      const intent = await call("/v1/uploads", session.jwt, {
        filename: file.name, mime: file.type, size: file.size, session_id: session.session_id,
      });
      const put = await fetch(intent.upload_url, { method: "PUT", headers: intent.headers, body: file });
      if (!put.ok) throw new Error(`upload failed (${put.status})`);
      return call(`/v1/uploads/${intent.file_id}/complete`, session.jwt, {});
    },
  };
}

queued and socket_closed are messages this file generates; every other message comes from the session.

4. Describe the place, then start. The first prompt builds the world, so send it before start:

import { openSession } from "./windflow-session.js";

const world = openSession("hy-nomas", document.querySelector("canvas"), (msg) => console.log(msg.type));
await world.ready; // worker_ready: commands are accepted from here
await world.command("set_prompt", {
  prompt: "A sunlit stone courtyard with a large central fountain, terracotta pots, a red wooden door on the left and a blue arched door on the right. Clear daylight, no people.",
});
await world.command("start");

5. Send held keys as one snapshot. WASD moves and the arrow keys turn the view. Send the complete held set as a set_input_state snapshot with a rising input_seq, on the open socket:

const KEYS = {
  KeyW: "forward", KeyA: "left", KeyS: "back", KeyD: "right",
  ArrowUp: "look_up", ArrowLeft: "look_left", ArrowDown: "look_down", ArrowRight: "look_right",
};
const held = new Set();
let inputSeq = 0;

function sendKeys() {
  world.socket.send(JSON.stringify({
    type: "set_input_state", input_seq: ++inputSeq, pressed_keys: [...held], client_ts: Date.now(),
  }));
}
addEventListener("keydown", (event) => {
  const key = KEYS[event.code];
  if (!key || held.has(key) || event.target.closest?.("input, textarea")) return;
  event.preventDefault(); // keep the arrow keys from scrolling the page
  held.add(key);
  sendKeys();
});
addEventListener("keyup", (event) => {
  if (held.delete(KEYS[event.code])) sendKeys();
});
addEventListener("blur", () => {
  held.clear();
  sendKeys();
});

6. Change what happens with a text event. A prompt sent during the run continues the same world from the next segment:

await world.command("set_prompt", {
  prompt: "The same courtyard as light rain begins, wet stone, grey sky",
});

prompt_accepted acknowledges the new text at once. prompt_applied arrives with the first frames generated from it, which is the moment to update a caption or an event log.

Wait until the session is ready

Capacity is brought up on demand, so POST /v1/sessions can answer status: "queued" with a queue_position and no transport offers. Keep polling GET /v1/sessions/{id}: a queue ticket nobody polls expires with error: "scheduler_queue_expired". When the status leaves queued, POST /v1/sessions with the same session_id returns the WebSocket offer without creating a second session.

On the socket, authenticate with the offer's launch_token must be the first message; client_hello with codecs: ["jpeg"] asks for one JPEG per binary message. Commands are accepted after worker_ready. Before it they fail with 409 queued or 409 no_active_session.

How segments shape the controls

Hy-Nomas does not read the keyboard every frame. At the start of each two-second segment it takes the held keys and the current prompt, generates that stretch of the world, and streams it. Four things follow:

• A change shows a few seconds after it is sent. Show the press in your interface as soon as input_accepted arrives, and let the picture follow at the next segment. A snapshot whose input_seq is not ahead of the last applied one comes back with stale: true and is not applied.
• Hold a key through a segment. Keys are read once per segment, so a press and release that both fall between two reads is not seen. Steady keys give the clearest motion.
• Movement is persistent state. It continues through later segments until it is released, which is why the example sends an empty snapshot on keyup and on window blur.
• Text events continue the same place. A mid-run set_prompt keeps the world and changes what happens in it. To go somewhere else, send reset, describe the new place with set_prompt, and start again.

The stream carries video only. Read video_config rather than hard-coding the 832 × 480 canvas, size the canvas with CSS, and add any sound on the page.

Write prompts as direct scene descriptions

Prompts reach the model in its native structured prompt format as written, with no rewriting or expansion. Name the place, the main objects and where they sit, the light and the viewpoint; concrete nouns and positions steer it more reliably than style adjectives. For a text event, restate the place and describe the change:

Plan each world as a 60-second take

Each world runs for up to 60 seconds, 1,440 frames at 24 fps, and then the session sends generation_complete. A session's time covers one full world, so open a new session for the next one. Start a countdown at the first painted frame, and plan a longer piece as a sequence of worlds.

Track arrived is not first frame visible

Enable the keys at the first painted frame, not at worker_ready. The session's transport.fallback_policy.first_frame_timeout_ms (10 seconds by default) is how long the platform's own client waits for media after generation_started.

Release the session on unmount

Call world.release() when the component unmounts and on pagehide. It sends { action: "detach", connection_id, release: true } with keepalive, which ends the session at the worker and hands the capacity back; the response reports session_released: true. A world nobody is steering is still a ready session, and paused time is billed, so release is what stops the meter. If a tab dies without releasing, the worker keeps the session for a reconnect grace (30 seconds by default). For drops, see recovering a dropped stream.

Troubleshooting by the stage where startup stopped

Rejected commands return 422 with a command_… code over HTTP and a command_error message on the socket.

FAQ

Does Hy-Nomas need a seed image?

No. A text prompt opens the world, and held keys and later prompts steer it. For world models that start from your own picture, see the seed image and prompt guide.

Can I use WebRTC with Hy-Nomas?

Yes. Hy-Nomas is offered over both ws-h264 and livekit. Request transport: "livekit" and join the room with the offer's url and participant_token; commands go to POST /v1/sessions/{id}/commands on both transports.

How long is one Hy-Nomas world?

Up to 60 seconds, 1,440 frames at 24 fps. Open a new session for the next world.

Can I run Hy-Nomas myself?

Yes. The weights are published on Hugging Face under Apache-2.0. The directory entry summarises the official setup steps and links the sources.