Standalone Functions

/**
 * Make a single prediction request to a Gradio application
 * @param app_reference - URL or HuggingFace Space reference
 * @param endpoint - Endpoint name or index
 * @param data - Input data array matching endpoint parameters
 * @param event_data - Optional event metadata
 * @returns Promise resolving to prediction results
 */
function predict(
  app_reference: string,
  endpoint: string | number,
  data?: unknown[] | Record<string, unknown>,
  event_data?: unknown
): Promise<PredictReturn>;

import { predict } from "@gradio/client";

// Simple text prediction
const result = await predict(
  "https://gradio-app-url",
  "/predict",
  ["Hello, world!"]
);
console.log(result.data);

// HuggingFace Space prediction
const result = await predict(
  "username/space-name",
  0, // Use endpoint index
  ["input text"]
);

// Multiple input parameters
const result = await predict(
  "https://app-url",
  "/process",
  [
    "text input",
    42,
    { option: "value" }
  ]
);

// With event data
const result = await predict(
  "https://app-url",
  "/predict",
  ["input"],
  { user_id: "12345", session: "abc" }
);

/**
 * Submit data for streaming results from a Gradio application
 * @param app_reference - URL or HuggingFace Space reference
 * @param endpoint - Endpoint name or index
 * @param data - Input data array matching endpoint parameters
 * @param event_data - Optional event metadata
 * @param trigger_id - Optional trigger identifier
 * @param all_events - Whether to receive all event types
 * @returns Async iterable of streaming events
 */
function submit(
  app_reference: string,
  endpoint: string | number,
  data?: unknown[] | Record<string, unknown>,
  event_data?: unknown,
  trigger_id?: number | null,
  all_events?: boolean
): SubmitIterable<GradioEvent>;

import { submit } from "@gradio/client";

// Basic streaming
const job = submit("https://app-url", "/generate", ["prompt text"]);
for await (const message of job) {
  if (message.type === "data") {
    console.log("Generated:", message.data);
  }
}

// Handle all event types
const job = submit(
  "username/space-name",
  "/stream",
  ["input"],
  null, // no event_data
  null, // no trigger_id
  true  // receive all events
);

for await (const message of job) {
  switch (message.type) {
    case "data":
      console.log("Result:", message.data);
      break;
    case "status":
      console.log("Status:", message.status?.stage);
      break;
    case "log":
      console.log("Log:", message.log);
      break;
    case "render":
      console.log("Render update");
      break;
  }
}

// Cancel streaming operation
const job = submit("https://app-url", "/long-process", ["input"]);
setTimeout(() => {
  job.cancel().then(() => {
    console.log("Job cancelled");
  });
}, 10000); // Cancel after 10 seconds

/**
 * Upload files to a Gradio server
 * @param root_url - Base URL of the Gradio application
 * @param files - Array of File or Blob objects to upload
 * @param upload_id - Optional upload session identifier
 * @returns Promise resolving to upload response with file information
 */
function upload_files(
  root_url: string,
  files: (Blob | File)[],
  upload_id?: string
): Promise<UploadResponse>;

import { upload_files } from "@gradio/client";

// Upload single file
const file = new File(["file content"], "document.txt", { 
  type: "text/plain" 
});
const response = await upload_files("https://app-url", [file]);
console.log("Uploaded files:", response);

// Upload multiple files
const files = [
  new File(["content 1"], "file1.txt"),
  new File(["content 2"], "file2.txt")
];
const response = await upload_files("https://app-url", files);

// Upload with session ID
const response = await upload_files(
  "https://app-url",
  [file],
  "upload-session-123"
);

/**
 * Convert File objects to FileData objects for processing
 * @param files - Array of File objects to convert
 * @param is_stream - Whether files should be treated as streams
 * @returns Promise resolving to array of FileData objects
 */
function prepare_files(files: File[], is_stream?: boolean): Promise<FileData[]>;

/**
 * Process various file input types into appropriate objects
 * @param file_or_url - File, string URL, Blob, or Buffer to process
 * @returns FileData, Blob, or Command object depending on input type
 */
function handle_file(file_or_url: File | string | Blob | Buffer): FileData | Blob | Command;

import { prepare_files, handle_file } from "@gradio/client";

// Prepare files for upload
const files = [
  new File(["content"], "file1.txt"),
  new File(["content"], "file2.txt")
];
const fileDataArray = await prepare_files(files);

// Handle different file input types
const fileData1 = handle_file(new File(["content"], "test.txt"));  // Returns FileData
const fileData2 = handle_file("https://example.com/image.jpg");     // Returns FileData  
const fileData3 = handle_file(new Blob(["content"]));              // Returns Blob
const fileData4 = handle_file(Buffer.from("content"));             // Returns FileData

// Process for streaming
const streamFiles = await prepare_files(files, true);

// AWS Lambda example
export const handler = async (event) => {
  const { text } = JSON.parse(event.body);
  
  const result = await predict(
    process.env.GRADIO_APP_URL,
    "/predict",
    [text]
  );
  
  return {
    statusCode: 200,
    body: JSON.stringify(result.data)
  };
};

import { predict } from "@gradio/client";

const inputs = ["text1", "text2", "text3"];
const results = await Promise.all(
  inputs.map(text => 
    predict("https://app-url", "/process", [text])
  )
);

console.log(results.map(r => r.data));

#!/usr/bin/env node
import { predict } from "@gradio/client";

const [,, appUrl, text] = process.argv;

if (!appUrl || !text) {
  console.error("Usage: script.js <app-url> <text>");
  process.exit(1);
}

try {
  const result = await predict(appUrl, "/predict", [text]);
  console.log(JSON.stringify(result.data, null, 2));
} catch (error) {
  console.error("Error:", error.message);
  process.exit(1);
}

// Standalone function approach
const result1 = await predict("app-url", "/predict", ["input1"]);
const result2 = await predict("app-url", "/predict", ["input2"]); // New connection

// Client class approach  
const client = await Client.connect("app-url"); // Single connection
const result1 = await client.predict("/predict", ["input1"]);
const result2 = await client.predict("/predict", ["input2"]); // Reuse connection
client.close();

import { predict } from "@gradio/client";

try {
  const result = await predict("https://app-url", "/predict", ["input"]);
  console.log(result.data);
} catch (error) {
  if (error.message.includes("queue full")) {
    console.log("Server busy, retrying in 5 seconds...");
    await new Promise(resolve => setTimeout(resolve, 5000));
    // Retry logic here
  } else if (error.message.includes("Could not connect")) {
    console.error("Application not accessible");
  } else {
    console.error("Prediction failed:", error.message);
  }
}

// Streaming error handling
const job = submit("https://app-url", "/stream", ["input"]);
try {
  for await (const message of job) {
    if (message.type === "status" && message.status?.code === "error") {
      console.error("Stream error:", message.status.message);
      break;
    }
  }
} catch (error) {
  console.error("Connection lost:", error.message);
}

/**
 * @deprecated Use `Client.connect()` instead. This method will be removed in v1.0.
 * Creates a client instance for interacting with Gradio apps.
 */
function client(
  app_reference: string,
  options?: ClientOptions
): Promise<Client>;

// Old (deprecated)
import { client } from "@gradio/client";
const gradioClient = await client("app-url");

// New (recommended)
import { Client } from "@gradio/client";
const gradioClient = await Client.connect("app-url");

/**
 * @deprecated Use `Client.duplicate()` instead. This method will be removed in v1.0.
 * Creates a duplicate of a space and returns a client instance for the duplicated space.
 */
function duplicate_space(
  app_reference: string,
  options?: DuplicateOptions
): Promise<Client>;

// Old (deprecated)
import { duplicate_space } from "@gradio/client";
const duplicatedClient = await duplicate_space("space-name", { hf_token: "token" });

// New (recommended)
import { Client } from "@gradio/client";
const duplicatedClient = await Client.duplicate("space-name", { hf_token: "token" });