Fusion SDK Overview

oomol-fusion-sdk is the SDK for calling Fusion API.

It is integrated into OOMOL Studio by default. In most cases, you use it inside Studio to turn OOMOL-hosted capabilities into reusable blocks. You can also call the same SDK directly from your own Node.js or Python services.

When To Use It

Use the Context API when your code needs to:

read block inputs
write outputs to downstream blocks
report progress
render preview data in Studio

Use the Fusion SDK when your code needs to:

call Fusion-hosted model and media capabilities
reuse Fusion task APIs such as submit -> state/result
call Fusion action APIs such as /action/{name}

The Main Path: Use It Inside Studio Blocks

If you are building a Scriptlet Block or Task Block in Studio, this is the preferred pattern:

Use the built-in Fusion SDK that comes with Studio.
Read the OOMOL token from context.
Read the Fusion base URL from context.
Create a FusionClient and call the service shortcut you need.

TypeScript:

import type { Context } from "@oomol/types/oocana";
import { FusionClient } from "oomol-fusion-sdk";

type Inputs = { pdf_url: string };
type Outputs = { markdown: string };

export default async function (
  params: Inputs,
  context: Context<Inputs, Outputs>
): Promise<Outputs> {
  const client = new FusionClient({
    token: await context.getOomolToken(),
    baseUrl: context.fusionApiUrl,
  });

  const markdown = await client.pdfTransformMarkdown.runData({
    pdfURL: params.pdf_url,
  });

  return { markdown };
}

Python:

from oocana import Context
from oomol_fusion_sdk import FusionClient

async def main(params: dict, context: Context) -> dict:
    client = FusionClient(
        token=await context.oomol_token(),
        base_url=context.fusion_api_url,
    )

    markdown = client.pdf_transform_markdown.run_data(
        {
            "pdfURL": params["pdf_url"],
        }
    )

    return {"markdown": markdown}

This keeps auth on the OOMOL token flow and avoids asking end users for an extra third-party API key when Fusion already covers the capability.

In other words, for normal block authoring inside Studio, you usually do not need to install oomol-fusion-sdk manually first.

Direct SDK Usage Outside Studio

You can also use the same SDK directly in your own app, backend, or script.

Node.js / TypeScript: initialize FusionClient({ apiKey }) or FusionClient({ token })
Python: initialize FusionClient(api_key=...) or FusionClient(token=...)

This mode is suitable when you are not running inside Studio and do not have a runtime context object. In this case, install the SDK as a normal dependency in your own project.

Two API Shapes

Fusion SDK is designed around two stable interface shapes in Fusion API:

Task APIs: submit, state, result, wait, run, waitData, runData
Action APIs: grouped shortcuts such as client.jinaReader.read(...), or raw calls such as client.action("jina-reader/search", ...)

In most cases:

prefer runData() / run_data() for task APIs
prefer grouped action shortcuts for action APIs
use request(...) only when the backend already added a new endpoint but the SDK shortcut is not available yet

When To Use It​

The Main Path: Use It Inside Studio Blocks​

Direct SDK Usage Outside Studio​

Two API Shapes​

Related Docs​

When To Use It

The Main Path: Use It Inside Studio Blocks

Direct SDK Usage Outside Studio

Two API Shapes

Related Docs