@unityclaw/sdk

Node.js SDK for UnityClaw API - AI-powered image/video generation, media analysis, document processing, and more.

Installation

npm install @unityclaw/sdk

Quick Start

import { UnityClawClient } from '@unityclaw/sdk';

// Reads UNITYCLAW_API_KEY from environment variable
const client = new UnityClawClient();

// Or with explicit config
const client = new UnityClawClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://unityclaw.com',
  taskDir: './tasks',
  timeout: 900000 // 15 minutes
});

// Generate image
const imageResult = await client.image.jimeng({
  prompt: 'A beautiful sunset over mountains',
  size: '2048x2048'
});

// Generate video (Kling)
const videoResult = await client.video.kling({
  prompt: 'A cat playing piano',
  model: 'kling-v2-6',
  aspect_ratio: '16:9',
  duration: '5'
});

// Translate document (local file will be auto-uploaded to get tmp_url)
const docResult = await client.document.translate({
  attachment: [{ path: './files/doc.pdf' }],
  source_language: { value: 'en', label: 'English' },
  target_language: { value: 'zh', label: 'Chinese' }
});

// Analyze media
const mediaResult = await client.media.analyze({
  url: [{ link: 'https://youtube.com/watch?v=...' }]
});

Configuration

Environment Variables

• UNITYCLAW_API_KEY - Your UnityClaw API key
• UNITYCLAW_BASE_URL - API base URL (optional, defaults to https://unityclaw.com)
• UNITYCLAW_OPENAPI_BASE_URL - Open API origin if it differs from the legacy API origin
• UNITYCLAW_OPENAPI_PREFIX - Open API route prefix (default: /openapi/v1)

CLI Configuration

Use the CLI to persist configuration:

# Install globally
npm install -g @unityclaw/sdk

# Set API key (stored in ~/.unityclaw/config.json)
unityclaw-sdk config set apiKey your-api-key

# Set custom base URL
unityclaw-sdk config set baseUrl https://custom.example.com

# View current configuration
unityclaw-sdk config

# Get a specific value
unityclaw-sdk config get apiKey

Configuration Priority

1. Constructor parameters (highest priority)
2. Environment variables
3. Config file (~/.unityclaw/config.json)
4. Default values (lowest priority)

OAuth Authorization

When no API key is configured, the SDK throws an AuthenticationRequiredError with the stable code AUTH_REQUIRED. An interactive caller should ask for the user's consent before starting OAuth.

After the user agrees, call loginWithOAuth(). It runs Authorization Code + PKCE with a loopback callback, exchanges the OAuth access token for an API key, and writes the API key to the existing ~/.unityclaw/config.json file. Business API requests continue to use X-Api-Key.

import {
  AuthenticationRequiredError,
  UnityClawClient,
  loginWithOAuth,
} from '@unityclaw/sdk';

try {
  const client = new UnityClawClient();
  // Use the client normally.
} catch (error) {
  if (error instanceof AuthenticationRequiredError) {
    // Ask the user for explicit consent in the calling UI first.
    await loginWithOAuth();
    const client = new UnityClawClient();
    // Retry the user's original operation once.
  }
}

loginWithOAuth() never runs automatically. Do not call it until the user has explicitly agreed to open the browser authorization flow.

Task Folders

Each SDK execution creates a task folder with:

• logs/request.json - Request details
• logs/response.json - API response
• logs/execution.log - Execution log
• attachments/ - Downloaded attachments (to avoid link expiration)

Default Task Directory

Tasks are stored in ~/Documents/tasks/ by default. You can override this:

const client = new UnityClawClient({
  taskDir: '/path/to/custom/tasks'
});

API Reference

Image Generation

// JiMeng
await client.image.jimeng({
  prompt: 'A sunset over mountains',
  size: '2048x2048'
});

// JiMeng (Doubao)
await client.image.jimeng({
  prompt: 'A futuristic city',
  model: 'v6.0'
});

Video Generation

// Kling
await client.video.kling({
  prompt: 'A dancing robot',
  model: 'kling-v1-5'
});

// Agent-safe pattern: one short submission, then separate one-shot status checks.
const submitted = await client.video.submitWan3({ prompt: 'A running horse', resolution: '1080P' });
console.log(submitted.taskId); // persist this ID before exiting the process

// In a later invocation, query once using the same API key and task ID.
const snapshot = await client.video.getVideoTask(submitted.taskId);
console.log(snapshot.status, snapshot.result, snapshot.error);

Nonblocking submit methods are submitHappyhorse, submitMiniMaxH3, submitWan3, submitSeedance25, submitSeedanceMini, and submitSeedance2 (fast and standard). An Agent should query the same ID every 5 seconds with a new short-lived command, stopping on succeeded or failed; a query error is never a reason to submit again. The older happyhorse, minimaxH3, wan3, seedance25, seedanceMini, and seedance2 methods wait internally and remain for non-Agent compatibility. Local attachments: [{ path: './reference.mp4' }] are uploaded before submission when auto-upload is enabled.

Document Processing

// Translate document
await client.document.translate({
  attachment: [{ tmp_url: 'https://...', name: 'doc.pdf' }],
  source_language: { value: 'en', label: 'English' },
  target_language: { value: 'zh', label: 'Chinese' }
});

// Convert document
await client.document.convert({
  attachment: [{ path: './files/doc.pdf' }],
  input_format: 'pdf',
  output_format: 'docx'
});

Media Analysis

const result = await client.media.analyze({
  url: [{ link: 'https://youtube.com/watch?v=...' }]
});

console.log(result.response.data?.summary);
console.log(result.response.data?.subtitle);

License

MIT