@vargai/sdk 0.1.1

package/lib/higgsfield/index.ts

@@ -0,0 +1,241 @@
+#!/usr/bin/env bun
+/**
+ * Higgsfield API client using HTTP requests
+ * Base client for all Higgsfield models
+ */
+
+const BASE_URL = "https://platform.higgsfield.ai";
+
+export interface HiggsfieldConfig {
+  apiKey?: string;
+  apiSecret?: string;
+}
+
+export type RequestStatus =
+  | "queued"
+  | "in_progress"
+  | "nsfw"
+  | "failed"
+  | "completed"
+  | "canceled";
+
+export interface GenerationRequest {
+  status: RequestStatus;
+  request_id: string;
+  status_url: string;
+  cancel_url: string;
+}
+
+export interface CompletedRequest extends GenerationRequest {
+  status: "completed";
+  images?: Array<{ url: string }>;
+  video?: { url: string };
+}
+
+export interface FailedRequest extends GenerationRequest {
+  status: "failed";
+  error: string;
+}
+
+export interface GenerationResponse {
+  status: RequestStatus;
+  request_id: string;
+  status_url: string;
+  cancel_url: string;
+  images?: Array<{ url: string }>;
+  video?: { url: string };
+  error?: string;
+}
+
+export class HiggsfieldClient {
+  private apiKey: string;
+  private apiSecret: string;
+
+  constructor(config?: HiggsfieldConfig) {
+    this.apiKey =
+      config?.apiKey ||
+      process.env.HIGGSFIELD_API_KEY ||
+      process.env.HF_API_KEY ||
+      "";
+    this.apiSecret =
+      config?.apiSecret ||
+      process.env.HIGGSFIELD_SECRET ||
+      process.env.HF_API_SECRET ||
+      "";
+
+    if (!this.apiKey || !this.apiSecret) {
+      throw new Error(
+        "Higgsfield API credentials not found. Set HIGGSFIELD_API_KEY and HIGGSFIELD_SECRET environment variables.",
+      );
+    }
+  }
+
+  private getAuthHeader(): string {
+    return `Key ${this.apiKey}:${this.apiSecret}`;
+  }
+
+  /**
+   * Submit a generation request to the queue
+   */
+  async submitRequest<T>(
+    modelId: string,
+    params: T,
+    webhook?: string,
+  ): Promise<GenerationResponse> {
+    const url = webhook
+      ? `${BASE_URL}/${modelId}?hf_webhook=${encodeURIComponent(webhook)}`
+      : `${BASE_URL}/${modelId}`;
+
+    console.log(`[higgsfield] submitting request to ${modelId}`);
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: this.getAuthHeader(),
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(params),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Higgsfield API error (${response.status}): ${errorText}`,
+      );
+    }
+
+    const data = (await response.json()) as GenerationResponse;
+    console.log(`[higgsfield] request queued: ${data.request_id}`);
+    return data;
+  }
+
+  /**
+   * Get the status of a generation request
+   */
+  async getStatus(requestId: string): Promise<GenerationResponse> {
+    const url = `${BASE_URL}/requests/${requestId}/status`;
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: this.getAuthHeader(),
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Higgsfield API error (${response.status}): ${errorText}`,
+      );
+    }
+
+    return (await response.json()) as GenerationResponse;
+  }
+
+  /**
+   * Cancel a pending request (only works in "queued" status)
+   */
+  async cancelRequest(requestId: string): Promise<boolean> {
+    const url = `${BASE_URL}/requests/${requestId}/cancel`;
+
+    console.log(`[higgsfield] canceling request: ${requestId}`);
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: this.getAuthHeader(),
+      },
+    });
+
+    if (response.status === 202) {
+      console.log(`[higgsfield] request canceled successfully`);
+      return true;
+    }
+
+    if (response.status === 400) {
+      console.log(`[higgsfield] request cannot be canceled (already processing)`);
+      return false;
+    }
+
+    const errorText = await response.text();
+    throw new Error(`Higgsfield API error (${response.status}): ${errorText}`);
+  }
+
+  /**
+   * Wait for a request to complete with polling
+   */
+  async waitForCompletion(
+    requestId: string,
+    options: {
+      pollingInterval?: number;
+      maxWaitTime?: number;
+      onUpdate?: (status: GenerationResponse) => void;
+    } = {},
+  ): Promise<GenerationResponse> {
+    const pollingInterval = options.pollingInterval || 2000; // 2 seconds
+    const maxWaitTime = options.maxWaitTime || 300000; // 5 minutes
+    const startTime = Date.now();
+
+    while (true) {
+      const status = await this.getStatus(requestId);
+
+      if (options.onUpdate) {
+        options.onUpdate(status);
+      }
+
+      // Check if completed, failed, or nsfw
+      if (
+        status.status === "completed" ||
+        status.status === "failed" ||
+        status.status === "nsfw" ||
+        status.status === "canceled"
+      ) {
+        return status;
+      }
+
+      // Check timeout
+      if (Date.now() - startTime > maxWaitTime) {
+        throw new Error(
+          `Request timeout after ${maxWaitTime}ms. Request ID: ${requestId}`,
+        );
+      }
+
+      // Wait before next poll
+      await new Promise((resolve) => setTimeout(resolve, pollingInterval));
+    }
+  }
+
+  /**
+   * Submit and wait for completion in one call
+   */
+  async generate<T>(
+    modelId: string,
+    params: T,
+    options: {
+      webhook?: string;
+      pollingInterval?: number;
+      maxWaitTime?: number;
+      onUpdate?: (status: GenerationResponse) => void;
+    } = {},
+  ): Promise<GenerationResponse> {
+    const request = await this.submitRequest(modelId, params, options.webhook);
+
+    // If webhook is provided, return immediately
+    if (options.webhook) {
+      console.log(`[higgsfield] webhook configured, returning request info`);
+      return request;
+    }
+
+    // Otherwise, wait for completion
+    return await this.waitForCompletion(request.request_id, {
+      pollingInterval: options.pollingInterval,
+      maxWaitTime: options.maxWaitTime,
+      onUpdate: options.onUpdate,
+    });
+  }
+}
+
+export default HiggsfieldClient;
+

package/lib/higgsfield/soul.ts

@@ -0,0 +1,262 @@
+#!/usr/bin/env bun
+/**
+ * Higgsfield Soul API - Image generation with Soul styles
+ */
+
+import HiggsfieldClient, {
+  type GenerationResponse,
+  type HiggsfieldConfig,
+} from "./index";
+
+const BASE_URL = "https://platform.higgsfield.ai";
+
+// Soul size options
+export const SoulSize = {
+  PORTRAIT_1152x2048: "1152x2048",
+  PORTRAIT_2048x1152: "2048x1152",
+  SQUARE_2048x2048: "2048x2048",
+  LANDSCAPE_1536x2048: "1536x2048",
+  LANDSCAPE_2016x1344: "2016x1344",
+} as const;
+
+// Quality options
+export const SoulQuality = {
+  SD: "720p",
+  HD: "1080p",
+} as const;
+
+// Batch size options
+export const BatchSize = {
+  SINGLE: 1,
+  FOUR: 4,
+} as const;
+
+export interface SoulGenerationParams {
+  prompt: string;
+  width_and_height?: (typeof SoulSize)[keyof typeof SoulSize];
+  quality?: (typeof SoulQuality)[keyof typeof SoulQuality];
+  style_id?: string;
+  batch_size?: (typeof BatchSize)[keyof typeof BatchSize];
+  enhance_prompt?: boolean;
+  seed?: number;
+  style_strength?: number;
+  image_reference?: string;
+  custom_reference_id?: string;
+  custom_reference_strength?: number;
+}
+
+export interface SoulStyle {
+  id: string;
+  name: string;
+  preview_url: string;
+  description?: string;
+}
+
+export class SoulClient extends HiggsfieldClient {
+  private static readonly MODEL_ID = "soul";
+
+  constructor(config?: HiggsfieldConfig) {
+    super(config);
+  }
+
+  /**
+   * Generate Soul images
+   */
+  async generateSoul(
+    params: SoulGenerationParams,
+    options: {
+      webhook?: string;
+      pollingInterval?: number;
+      maxWaitTime?: number;
+      onUpdate?: (status: GenerationResponse) => void;
+    } = {},
+  ): Promise<GenerationResponse> {
+    console.log(`[higgsfield:soul] generating image`);
+    console.log(`[higgsfield:soul] prompt: ${params.prompt}`);
+
+    return await this.generate(SoulClient.MODEL_ID, params, {
+      ...options,
+      onUpdate: (status) => {
+        console.log(`[higgsfield:soul] status: ${status.status}`);
+        if (options.onUpdate) {
+          options.onUpdate(status);
+        }
+      },
+    });
+  }
+
+  /**
+   * Get available Soul styles
+   */
+  async getSoulStyles(): Promise<SoulStyle[]> {
+    console.log("[higgsfield:soul] fetching soul styles");
+
+    const url = `${BASE_URL}/v1/text2image/soul-styles`;
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Key ${process.env.HIGGSFIELD_API_KEY || process.env.HF_API_KEY}:${process.env.HIGGSFIELD_SECRET || process.env.HF_API_SECRET}`,
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Higgsfield API error (${response.status}): ${errorText}`,
+      );
+    }
+
+    const styles = (await response.json()) as SoulStyle[];
+    console.log(`[higgsfield:soul] found ${styles.length} styles`);
+    return styles;
+  }
+}
+
+// Convenience function for generating Soul images
+export async function generateSoul(
+  params: SoulGenerationParams,
+  config?: HiggsfieldConfig,
+): Promise<GenerationResponse> {
+  const client = new SoulClient(config);
+  return await client.generateSoul(params);
+}
+
+// Convenience function for listing styles
+export async function listSoulStyles(
+  config?: HiggsfieldConfig,
+): Promise<SoulStyle[]> {
+  const client = new SoulClient(config);
+  return await client.getSoulStyles();
+}
+
+// CLI runner
+if (import.meta.main) {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case "generate": {
+      if (!args[0]) {
+        console.log(`
+usage:
+  bun run lib/higgsfield/soul.ts generate <prompt> [styleId] [webhook]
+
+examples:
+  bun run lib/higgsfield/soul.ts generate "beautiful sunset"
+  bun run lib/higgsfield/soul.ts generate "portrait of a woman" "style-id-123"
+  bun run lib/higgsfield/soul.ts generate "landscape" "" "https://webhook.url"
+        `);
+        process.exit(1);
+      }
+
+      const result = await generateSoul({
+        prompt: args[0],
+        style_id: args[1] || undefined,
+        width_and_height: SoulSize.PORTRAIT_1152x2048,
+        quality: SoulQuality.HD,
+        batch_size: BatchSize.SINGLE,
+        enhance_prompt: false,
+      });
+
+      console.log("\n=== Generation Result ===");
+      console.log(`Request ID: ${result.request_id}`);
+      console.log(`Status: ${result.status}`);
+
+      if (result.status === "completed" && result.images) {
+        console.log("\nGenerated Images:");
+        for (const image of result.images) {
+          console.log(`  - ${image.url}`);
+        }
+      } else if (result.status === "failed") {
+        console.log(`\nError: ${result.error}`);
+      } else if (result.status === "nsfw") {
+        console.log("\nContent failed moderation (NSFW)");
+      }
+
+      break;
+    }
+
+    case "list_styles": {
+      const styles = await listSoulStyles();
+
+      console.log("\n=== Soul Styles ===");
+      for (const style of styles) {
+        console.log(`\nID: ${style.id}`);
+        console.log(`Name: ${style.name}`);
+        console.log(`Preview: ${style.preview_url}`);
+        if (style.description) {
+          console.log(`Description: ${style.description}`);
+        }
+      }
+
+      break;
+    }
+
+    case "status": {
+      if (!args[0]) {
+        console.log(`
+usage:
+  bun run lib/higgsfield/soul.ts status <request_id>
+        `);
+        process.exit(1);
+      }
+
+      const client = new SoulClient();
+      const status = await client.getStatus(args[0]);
+
+      console.log("\n=== Request Status ===");
+      console.log(JSON.stringify(status, null, 2));
+
+      break;
+    }
+
+    case "cancel": {
+      if (!args[0]) {
+        console.log(`
+usage:
+  bun run lib/higgsfield/soul.ts cancel <request_id>
+        `);
+        process.exit(1);
+      }
+
+      const client = new SoulClient();
+      const canceled = await client.cancelRequest(args[0]);
+
+      if (canceled) {
+        console.log("\n✓ Request canceled successfully");
+      } else {
+        console.log("\n✗ Request could not be canceled (already processing)");
+      }
+
+      break;
+    }
+
+    default:
+      console.log(`
+usage:
+  bun run lib/higgsfield/soul.ts generate <prompt> [styleId] [webhook]
+  bun run lib/higgsfield/soul.ts list_styles
+  bun run lib/higgsfield/soul.ts status <request_id>
+  bun run lib/higgsfield/soul.ts cancel <request_id>
+
+examples:
+  # Generate image
+  bun run lib/higgsfield/soul.ts generate "beautiful landscape"
+  
+  # Generate with style
+  bun run lib/higgsfield/soul.ts generate "portrait" "style-id-123"
+  
+  # List available styles
+  bun run lib/higgsfield/soul.ts list_styles
+  
+  # Check request status
+  bun run lib/higgsfield/soul.ts status "request-id-here"
+  
+  # Cancel pending request
+  bun run lib/higgsfield/soul.ts cancel "request-id-here"
+      `);
+      process.exit(1);
+  }
+}
+

package/lib/higgsfield.ts

@@ -0,0 +1,176 @@
+#!/usr/bin/env bun
+/**
+ * higgsfield client wrapper for soul image generation and character creation
+ * usage: bun run lib/higgsfield.ts <command> <args>
+ */
+
+import {
+  BatchSize,
+  HiggsfieldClient,
+  InputImageType,
+  SoulQuality,
+  SoulSize,
+} from "@higgsfield/client";
+
+const client = new HiggsfieldClient({
+  apiKey: process.env.HIGGSFIELD_API_KEY || process.env.HF_API_KEY,
+  apiSecret: process.env.HIGGSFIELD_SECRET || process.env.HF_API_SECRET,
+});
+
+export interface GenerateSoulArgs {
+  prompt: string;
+  widthAndHeight?: (typeof SoulSize)[keyof typeof SoulSize];
+  quality?: (typeof SoulQuality)[keyof typeof SoulQuality];
+  styleId?: string;
+  batchSize?: (typeof BatchSize)[keyof typeof BatchSize];
+  enhancePrompt?: boolean;
+}
+
+export interface CreateSoulIdArgs {
+  name: string;
+  imageUrls: string[];
+}
+
+export async function generateSoul(args: GenerateSoulArgs) {
+  console.log("[higgsfield] generating soul image");
+  console.log(`[higgsfield] prompt: ${args.prompt}`);
+
+  try {
+    const jobSet = await client.generate("/v1/text2image/soul", {
+      prompt: args.prompt,
+      width_and_height: args.widthAndHeight || SoulSize.PORTRAIT_1152x2048,
+      quality: args.quality || SoulQuality.HD,
+      style_id: args.styleId,
+      batch_size: args.batchSize || BatchSize.SINGLE,
+      enhance_prompt: args.enhancePrompt ?? false,
+    });
+
+    console.log(`[higgsfield] job created: ${jobSet.id}`);
+    console.log(`[higgsfield] completed: ${jobSet.isCompleted}`);
+
+    return jobSet;
+  } catch (error) {
+    console.error("[higgsfield] error:", error);
+    throw error;
+  }
+}
+
+export async function listSoulStyles() {
+  console.log("[higgsfield] fetching soul styles");
+
+  try {
+    const styles = await client.getSoulStyles();
+    return styles;
+  } catch (error) {
+    console.error("[higgsfield] error:", error);
+    throw error;
+  }
+}
+
+export async function createSoulId(args: CreateSoulIdArgs) {
+  console.log(`[higgsfield] creating soul id: ${args.name}`);
+  console.log(`[higgsfield] images: ${args.imageUrls.length}`);
+
+  try {
+    const soulId = await client.createSoulId({
+      name: args.name,
+      input_images: args.imageUrls.map((url) => ({
+        type: InputImageType.IMAGE_URL,
+        image_url: url,
+      })),
+    });
+
+    console.log(`[higgsfield] soul id created: ${soulId.id}`);
+    return soulId;
+  } catch (error) {
+    console.error("[higgsfield] error:", error);
+    throw error;
+  }
+}
+
+export async function listSoulIds(page = 1, pageSize = 20) {
+  console.log("[higgsfield] listing soul ids");
+
+  try {
+    const soulIds = await client.listSoulIds(page, pageSize);
+    return soulIds;
+  } catch (error) {
+    console.error("[higgsfield] error:", error);
+    throw error;
+  }
+}
+
+// cli runner
+if (import.meta.main) {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case "generate_soul": {
+      if (!args[0]) {
+        console.log(`
+usage:
+  bun run lib/higgsfield.ts generate_soul <prompt> [styleId]
+        `);
+        process.exit(1);
+      }
+      const soulResult = await generateSoul({
+        prompt: args[0],
+        styleId: args[1],
+      });
+
+      // print job status and results
+      console.log(`\njob id: ${soulResult.id}`);
+      console.log(
+        `status: completed=${soulResult.isCompleted}, failed=${soulResult.isFailed}`,
+      );
+
+      if (soulResult.isCompleted && soulResult.jobs.length > 0) {
+        for (const job of soulResult.jobs) {
+          if (job.results) {
+            console.log(`\nimage url: ${job.results.raw.url}`);
+          }
+        }
+      }
+      break;
+    }
+
+    case "list_styles": {
+      const styles = await listSoulStyles();
+      console.log(JSON.stringify(styles, null, 2));
+      break;
+    }
+
+    case "create_soul_id": {
+      if (!args[0] || !args[1]) {
+        console.log(`
+usage:
+  bun run lib/higgsfield.ts create_soul_id <name> <imageUrl1> [imageUrl2...]
+        `);
+        process.exit(1);
+      }
+      const imageUrls = args.slice(1);
+      const soulIdResult = await createSoulId({
+        name: args[0],
+        imageUrls,
+      });
+      console.log(JSON.stringify(soulIdResult, null, 2));
+      break;
+    }
+
+    case "list_soul_ids": {
+      const soulIds = await listSoulIds();
+      console.log(JSON.stringify(soulIds, null, 2));
+      break;
+    }
+
+    default:
+      console.log(`
+usage:
+  bun run lib/higgsfield.ts generate_soul <prompt> [styleId]
+  bun run lib/higgsfield.ts list_styles
+  bun run lib/higgsfield.ts create_soul_id <name> <imageUrl1> [imageUrl2...]
+  bun run lib/higgsfield.ts list_soul_ids
+      `);
+      process.exit(1);
+  }
+}