Browser Polling

In this tutorial you will build an async image flow where:

Your server creates a Mynth task with your API key.
Mynth returns a task ID and a short-lived Public Access Token (PAT).
The browser polls task status and results with that PAT — never with your API key.

By the end you will have a complete create → poll → render path you can drop into an interactive app.

Why this pattern

Task creation (POST /image/generate) requires a Mynth API key. Put that call on the server. GET /tasks/:id/status and GET /tasks/:id/result also accept a task-scoped PAT. That is what the browser uses for live progress without a polling proxy. CORS is open on those two endpoints so browser fetch works from your frontend origin. Other API routes are not open for arbitrary browser origins.

Step 1. Create the task on your server

Keep the SDK and API key server-side only:

import Mynth from "@mynthio/sdk";

const mynth = new Mynth({
  apiKey: process.env.MYNTH_API_KEY,
});

export async function createGeneration() {
  const task = await mynth.image.generateAsync({
    prompt: "A clean landing page hero illustration for a fintech startup",
    model: "google/gemini-3.1-flash-image",
  });

  return {
    taskId: task.id,
    publicAccessToken: task.access.publicAccessToken,
  };
}

generateAsync() returns a TaskAsync immediately. Generation tasks include a PAT by default (task.access.publicAccessToken). Disable it when you only poll from the server with your API key:

const task = await mynth.image.generateAsync({
  prompt: "A clean landing page hero illustration for a fintech startup",
  model: "google/gemini-3.1-flash-image",
  access: { pat: { enabled: false } },
});

About the PAT:

JWT string with a pat_ prefix
Scoped to this single task ID
Valid for one hour (generation PATs)
Usable only on GET /tasks/:id/status and GET /tasks/:id/result

Rating and alt text tasks currently do not return a PAT. Poll those from trusted server code with your API key.

Step 2. Return only safe data to the browser

Your app’s API response should include:

taskId
publicAccessToken

Do not return MYNTH_API_KEY, the full task object from GET /tasks/:id, or other owner-only fields. Example response:

{
  "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
  "publicAccessToken": "pat_eyJhbGciOi..."
}

Step 3. Poll status from the browser

Use raw fetch with the PAT as a Bearer token. Do not call the SDK from the browser with your API key, and do not rely on task.wait() in client code — wait() is for server-side use with the SDK client.

type TaskStatus = "pending" | "completed" | "failed";

async function getTaskStatus(taskId: string, publicAccessToken: string): Promise<TaskStatus> {
  const response = await fetch(`https://api.mynth.io/tasks/${taskId}/status`, {
    headers: {
      Authorization: `Bearer ${publicAccessToken}`,
    },
  });

  if (response.status === 401 || response.status === 403) {
    throw new Error("Public access token is invalid or expired");
  }

  if (!response.ok) {
    throw new Error(`Status request failed: ${response.status}`);
  }

  const body = (await response.json()) as {
    data: { status: TaskStatus };
  };

  return body.data.status;
}

Status response:

{
  "data": {
    "status": "pending"
  }
}

Possible values: pending, completed, failed.

Step 4. Poll until terminal, then fetch results

A simple client loop:

const POLL_MS = 2500;
const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes

async function waitForTask(taskId: string, publicAccessToken: string) {
  const startedAt = Date.now();

  while (Date.now() - startedAt < TIMEOUT_MS) {
    const status = await getTaskStatus(taskId, publicAccessToken);

    if (status === "completed") {
      return getTaskResult(taskId, publicAccessToken);
    }

    if (status === "failed") {
      throw new Error(`Task ${taskId} failed`);
    }

    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
  }

  throw new Error(`Timed out waiting for task ${taskId}`);
}

async function getTaskResult(taskId: string, publicAccessToken: string) {
  const response = await fetch(`https://api.mynth.io/tasks/${taskId}/result`, {
    headers: {
      Authorization: `Bearer ${publicAccessToken}`,
    },
  });

  if (response.status === 401 || response.status === 403) {
    throw new Error("Public access token is invalid or expired");
  }

  if (!response.ok) {
    throw new Error(`Result request failed: ${response.status}`);
  }

  const body = (await response.json()) as {
    data: {
      id: string;
      type: "image.generate";
      status: "pending" | "completed" | "failed";
      result: {
        model: string;
        images: Array<
          | {
              status: "success";
              id: string;
              url: string | null;
              mynth_url: string;
              cost: string;
              size: string;
            }
          | {
              status: "failed";
              error: { code: string; message?: string };
            }
        >;
      } | null;
    };
  };

  return body.data;
}

Successful image.generate result shape:

{
  "data": {
    "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "type": "image.generate",
    "status": "completed",
    "result": {
      "model": "google/gemini-3.1-flash-image",
      "images": [
        {
          "status": "success",
          "id": "img_123",
          "url": "https://...",
          "mynth_url": "https://...",
          "cost": "0.01250000",
          "size": "1024x1024"
        }
      ]
    }
  }
}

Handle both task-level and per-image failure:

const task = await waitForTask(taskId, publicAccessToken);

if (task.status !== "completed" || !task.result) {
  throw new Error("Task did not complete successfully");
}

const urls: string[] = [];

for (const image of task.result.images) {
  if (image.status === "success") {
    // Prefer mynth_url when you need a stable CDN URL
    urls.push(image.mynth_url);
  } else {
    console.error(image.error.code, image.error.message);
  }
}

Notes:

A completed task can still include individual status: "failed" images.
url can be null when delivery is destination-only; mynth_url is still present on success.
GET /tasks/:id/result does not include the owner-only errors array. For full task diagnostics, call GET /tasks/:id from the server with your API key.

Step 5. Map states in the UI

Status	UI
`pending`	Loading / progress
`completed`	Fetch result and render successful images
`failed`	Show failure and offer retry (create a new task server-side)
network / 401	Retry a few times, or refresh the flow if the PAT expired

Suggested client behavior:

Poll every ~2.5s while the user is waiting (same order of magnitude as the SDK’s fast phase).
Stop on completed or failed.
Cap wait time (for example 5 minutes).
Treat 401/403 as an expired or invalid PAT — start a new generation from the server rather than reusing the token.

What the PAT cannot do

A Public Access Token is not a substitute for your API key. It cannot:

Create tasks
Access other task IDs
Call GET /tasks/:id (full owner-only task details)

For deeper polling options, intervals used by TaskAsync.wait(), and owner-only endpoints, read Async and polling and SDK tasks.

When to use webhooks instead

Polling fits:

interactive product flows
browser previews
short-lived user sessions

Webhooks fit:

backend processing after generation
durable pipelines
systems that should not keep a browser tab open

See Use webhooks when the result should trigger server-side work.

Getting started

Generation

Control and delivery

Image analysis

Integrations

Why this pattern

Step 1. Create the task on your server

Step 2. Return only safe data to the browser

Step 3. Poll status from the browser

Step 4. Poll until terminal, then fetch results

Step 5. Map states in the UI

What the PAT cannot do

When to use webhooks instead

​Why this pattern

​Step 1. Create the task on your server

​Step 2. Return only safe data to the browser

​Step 3. Poll status from the browser

​Step 4. Poll until terminal, then fetch results

​Step 5. Map states in the UI

​What the PAT cannot do

​When to use webhooks instead

Why this pattern

Step 1. Create the task on your server

Step 2. Return only safe data to the browser

Step 3. Poll status from the browser

Step 4. Poll until terminal, then fetch results

Step 5. Map states in the UI

What the PAT cannot do

When to use webhooks instead