@acedatacloud/sdk 2026.716.0 → 2026.718.0

package/src/resources/kling.ts

@@ -2,41 +2,200 @@
 
 import { Transport } from '../runtime/transport';
 
-export type KlingModel =
-  | 'kling-v1'
-  | 'kling-v1-6'
-  | 'kling-v2-master'
-  | 'kling-v2-1-master'
-  | 'kling-v2-5-turbo'
-  | 'kling-v2-6'
-  | 'kling-v3'
-  | 'kling-v3-omni'
-  | 'kling-video-o1'
-  | (string & {});
+export const KLING_MODELS = [
+  'kling-v1',
+  'kling-v1-6',
+  'kling-v2-master',
+  'kling-v2-1-master',
+  'kling-v2-5-turbo',
+  'kling-v2-6',
+  'kling-v3',
+  'kling-v3-omni',
+  'kling-o1',
+] as const;
+
+export type KlingModel = (typeof KLING_MODELS)[number];
+
+export interface KlingCameraControl {
+  type: 'simple' | 'down_back' | 'forward_up' | 'left_turn_forward' | 'right_turn_forward';
+  config?: {
+    horizontal?: number;
+    vertical?: number;
+    pan?: number;
+    tilt?: number;
+    roll?: number;
+    zoom?: number;
+  };
+}
+
+export interface KlingReferenceImage {
+  imageUrl: string;
+  type?: 'first_frame' | 'end_frame';
+}
+
+export interface KlingReferenceVideo {
+  videoUrl: string;
+  referType?: 'base' | 'feature';
+  keepOriginalSound?: 'yes' | 'no';
+}
+
+export interface KlingGenerateOptions {
+  action: 'text2video' | 'image2video' | 'extend';
+  mode?: 'std' | 'pro' | '4k';
+  model: KlingModel;
+  prompt?: string;
+  duration?: number;
+  generateAudio?: boolean;
+  videoId?: string;
+  cfgScale?: number;
+  aspectRatio?: '16:9' | '9:16' | '1:1';
+  callbackUrl?: string;
+  async?: boolean;
+  timeout?: number;
+  endImageUrl?: string;
+  cameraControl?: KlingCameraControl;
+  imageList?: KlingReferenceImage[];
+  videoList?: KlingReferenceVideo[];
+  negativePrompt?: string;
+  startImageUrl?: string;
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function validateGenerateOptions(opts: KlingGenerateOptions): void {
+  if (!KLING_MODELS.includes(opts.model)) {
+    throw new Error(`model must be one of: ${KLING_MODELS.join(', ')}`);
+  }
+  const isV3 = opts.model === 'kling-v3' || opts.model === 'kling-v3-omni';
+  const hasReferences = Boolean(opts.imageList?.length || opts.videoList?.length);
+
+  if (opts.imageList !== undefined && opts.imageList.length === 0) {
+    throw new Error('imageList must be non-empty or omitted');
+  }
+  if (opts.videoList !== undefined && opts.videoList.length === 0) {
+    throw new Error('videoList must be non-empty or omitted');
+  }
+
+  if ((opts.action === 'text2video' || opts.action === 'image2video') && !opts.prompt) {
+    throw new Error('prompt is required for text2video and image2video');
+  }
+  if (opts.action === 'image2video' && !opts.startImageUrl) {
+    throw new Error('startImageUrl is required for image2video');
+  }
+  if (opts.action === 'extend' && !opts.videoId) {
+    throw new Error('videoId is required for extend');
+  }
+  if (opts.endImageUrl && !opts.startImageUrl) {
+    throw new Error('startImageUrl is required with endImageUrl');
+  }
+  if (opts.startImageUrl && !isHttpUrl(opts.startImageUrl)) {
+    throw new Error('startImageUrl must be an HTTP URL');
+  }
+  if (opts.endImageUrl && !isHttpUrl(opts.endImageUrl)) {
+    throw new Error('endImageUrl must be an HTTP URL');
+  }
+  if (opts.callbackUrl && !isHttpUrl(opts.callbackUrl)) {
+    throw new Error('callbackUrl must be an HTTP URL');
+  }
+  if (opts.cfgScale !== undefined && (opts.cfgScale < 0 || opts.cfgScale > 1)) {
+    throw new Error('cfgScale must be between 0 and 1');
+  }
+  if (opts.duration !== undefined && !Number.isInteger(opts.duration)) {
+    throw new Error('duration must be an integer');
+  }
+  if (isV3 && opts.duration !== undefined && (opts.duration < 3 || opts.duration > 15)) {
+    throw new Error('Kling V3 duration must be between 3 and 15 seconds');
+  }
+  if (!isV3 && opts.model !== 'kling-o1' && opts.duration !== undefined && ![5, 10].includes(opts.duration)) {
+    throw new Error('This Kling model supports only 5- or 10-second generation');
+  }
+  if (opts.model === 'kling-o1' && opts.duration !== undefined && opts.duration !== 5) {
+    throw new Error('kling-o1 supports only 5-second generation');
+  }
+  if (opts.model === 'kling-o1' && opts.mode !== undefined && !['std', 'pro'].includes(opts.mode)) {
+    throw new Error('kling-o1 supports only std and pro modes');
+  }
+  if (opts.mode === '4k' && !isV3) {
+    throw new Error('4k mode requires kling-v3 or kling-v3-omni');
+  }
+  if (opts.action === 'extend' && !['kling-v1', 'kling-v1-6', 'kling-v2-5-turbo'].includes(opts.model)) {
+    throw new Error('extend requires kling-v1, kling-v1-6, or kling-v2-5-turbo');
+  }
+  if (opts.action === 'extend' && hasReferences) {
+    throw new Error('imageList and videoList are not supported with extend');
+  }
+  if (hasReferences && opts.model !== 'kling-o1' && opts.model !== 'kling-v3-omni') {
+    throw new Error('Omni references require kling-o1 or kling-v3-omni');
+  }
+  if (hasReferences && opts.mode === '4k') {
+    throw new Error('4k cannot be combined with Omni references');
+  }
+  if ((opts.model === 'kling-o1' || hasReferences) && (opts.negativePrompt !== undefined || opts.cameraControl !== undefined || opts.cfgScale !== undefined)) {
+    throw new Error('Kling O1 and Omni references do not support negativePrompt, cameraControl, or cfgScale');
+  }
+  if (opts.model === 'kling-o1' && opts.generateAudio) {
+    throw new Error('kling-o1 does not support generateAudio');
+  }
+  if (opts.generateAudio && !isV3 && opts.model !== 'kling-v2-6') {
+    throw new Error('generateAudio requires a V3 model or kling-v2-6 pro mode');
+  }
+  if (opts.generateAudio && opts.model === 'kling-v2-6' && opts.mode !== 'pro') {
+    throw new Error('kling-v2-6 supports generateAudio only in pro mode');
+  }
+  if (opts.generateAudio && opts.videoList?.length) {
+    throw new Error('generateAudio cannot be used with videoList');
+  }
+  if (opts.videoList && (opts.videoList.length === 0 || opts.videoList.length > 1)) {
+    throw new Error('videoList must contain exactly one reference video');
+  }
+
+  for (const image of opts.imageList ?? []) {
+    if (!isHttpUrl(image.imageUrl)) throw new Error('Every reference image requires an HTTP imageUrl');
+    if (image.type !== undefined && !['first_frame', 'end_frame'].includes(image.type)) {
+      throw new Error('Reference image type must be first_frame or end_frame');
+    }
+  }
+  for (const video of opts.videoList ?? []) {
+    if (!isHttpUrl(video.videoUrl)) throw new Error('Every reference video requires an HTTP videoUrl');
+    if (video.referType !== undefined && !['base', 'feature'].includes(video.referType)) {
+      throw new Error('Reference video referType must be base or feature');
+    }
+    if (video.keepOriginalSound !== undefined && !['yes', 'no'].includes(video.keepOriginalSound)) {
+      throw new Error('Reference video keepOriginalSound must be yes or no');
+    }
+  }
+
+  const firstFrames = Number(Boolean(opts.startImageUrl)) + (opts.imageList ?? []).filter((item) => item.type === 'first_frame').length;
+  const endFrames = Number(Boolean(opts.endImageUrl)) + (opts.imageList ?? []).filter((item) => item.type === 'end_frame').length;
+  if (firstFrames > 1 || endFrames > 1) {
+    throw new Error('Only one first frame and one end frame are allowed');
+  }
+  if (endFrames > 0 && firstFrames === 0) {
+    throw new Error('A first frame is required with an end frame');
+  }
+  if ((opts.videoList?.[0]?.referType ?? 'base') === 'base' && opts.videoList?.length && (firstFrames > 0 || endFrames > 0)) {
+    throw new Error('A base reference video cannot be combined with first or end frames');
+  }
+
+  const imageCount = (opts.imageList?.length ?? 0) + Number(Boolean(opts.startImageUrl)) + Number(Boolean(opts.endImageUrl));
+  const imageLimit = opts.videoList?.length ? 4 : 7;
+  if (imageCount > imageLimit) {
+    throw new Error(`Reference images cannot exceed ${imageLimit} for this request`);
+  }
+}
 
 export class Kling {
   constructor(private transport: Transport) {}
 
-  async generate(opts: {
-    action: 'text2video' | 'image2video' | 'extend';
-    mode?: 'std' | 'pro' | '4k';
-    model?: KlingModel;
-    prompt?: string;
-    duration?: 5 | 10;
-    generateAudio?: boolean;
-    videoId?: string;
-    cfgScale?: number;
-    aspectRatio?: '16:9' | '9:16' | '1:1';
-    callbackUrl?: string;
-    async?: boolean;
-    endImageUrl?: string;
-    cameraControl?: string;
-    elementList?: unknown[];
-    videoList?: unknown[];
-    negativePrompt?: string;
-    startImageUrl?: string;
-    [key: string]: unknown;
-  }): Promise<Record<string, unknown>> {
+  async generate(opts: KlingGenerateOptions): Promise<Record<string, unknown>> {
+    validateGenerateOptions(opts);
     const {
       action,
       mode,
@@ -48,15 +207,16 @@ export class Kling {
       cfgScale,
       aspectRatio,
       callbackUrl,
+      async: asyncMode,
+      timeout,
       endImageUrl,
       cameraControl,
-      elementList,
+      imageList,
       videoList,
       negativePrompt,
       startImageUrl,
-      ...rest
     } = opts;
-    const body: Record<string, unknown> = { action, ...rest };
+    const body: Record<string, unknown> = { action };
     if (mode !== undefined) body.mode = mode;
     if (model !== undefined) body.model = model;
     if (prompt !== undefined) body.prompt = prompt;
@@ -66,10 +226,20 @@ export class Kling {
     if (cfgScale !== undefined) body.cfg_scale = cfgScale;
     if (aspectRatio !== undefined) body.aspect_ratio = aspectRatio;
     if (callbackUrl !== undefined) body.callback_url = callbackUrl;
+    if (asyncMode !== undefined) body.async = asyncMode;
+    if (timeout !== undefined) body.timeout = timeout;
     if (endImageUrl !== undefined) body.end_image_url = endImageUrl;
     if (cameraControl !== undefined) body.camera_control = cameraControl;
-    if (elementList !== undefined) body.element_list = elementList;
-    if (videoList !== undefined) body.video_list = videoList;
+    if (imageList !== undefined) {
+      body.image_list = imageList.map(({ imageUrl, type }) => ({ image_url: imageUrl, ...(type ? { type } : {}) }));
+    }
+    if (videoList !== undefined) {
+      body.video_list = videoList.map(({ videoUrl, referType, keepOriginalSound }) => ({
+        video_url: videoUrl,
+        ...(referType ? { refer_type: referType } : {}),
+        ...(keepOriginalSound ? { keep_original_sound: keepOriginalSound } : {}),
+      }));
+    }
     if (negativePrompt !== undefined) body.negative_prompt = negativePrompt;
     if (startImageUrl !== undefined) body.start_image_url = startImageUrl;
     return this.transport.request('POST', '/kling/videos', { json: body });
@@ -84,19 +254,28 @@ export class Kling {
     prompt?: string;
     callbackUrl?: string;
     async?: boolean;
-    [key: string]: unknown;
   }): Promise<Record<string, unknown>> {
-    const { mode, imageUrl, videoUrl, characterOrientation, keepOriginalSound, prompt, callbackUrl, ...rest } = opts;
+    const { mode, imageUrl, videoUrl, characterOrientation, keepOriginalSound, prompt, callbackUrl } = opts;
+    if (!['std', 'pro'].includes(mode)) throw new Error('mode must be std or pro');
+    if (!isHttpUrl(imageUrl)) throw new Error('imageUrl must be an HTTP URL');
+    if (!isHttpUrl(videoUrl)) throw new Error('videoUrl must be an HTTP URL');
+    if (!['image', 'video'].includes(characterOrientation)) {
+      throw new Error('characterOrientation must be image or video');
+    }
+    if (keepOriginalSound !== undefined && !['yes', 'no'].includes(keepOriginalSound)) {
+      throw new Error('keepOriginalSound must be yes or no');
+    }
+    if (callbackUrl && !isHttpUrl(callbackUrl)) throw new Error('callbackUrl must be an HTTP URL');
     const body: Record<string, unknown> = {
       mode,
       image_url: imageUrl,
       video_url: videoUrl,
       character_orientation: characterOrientation,
-      ...rest,
     };
     if (keepOriginalSound !== undefined) body.keep_original_sound = keepOriginalSound;
     if (prompt !== undefined) body.prompt = prompt;
     if (callbackUrl !== undefined) body.callback_url = callbackUrl;
+    if (opts.async !== undefined) body.async = opts.async;
     return this.transport.request('POST', '/kling/motion', { json: body });
   }
 }

package/src/runtime/transport.ts

@@ -68,6 +68,18 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function isAbortError(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'name' in error && error.name === 'AbortError';
+}
+
+function timeoutError(error: unknown): TimeoutError {
+  return new TimeoutError({
+    message: `Request timed out${error instanceof Error && error.message ? `: ${error.message}` : ''}`,
+    statusCode: 0,
+    code: 'timeout',
+  });
+}
+
 export interface TransportOptions {
   apiToken?: string;
   baseURL?: string;
@@ -104,7 +116,7 @@ export class Transport {
         code: 'no_token',
       });
     }
-    this.baseURL = (opts.baseURL ?? 'https://api.acedata.cloud').replace(/\/+$/, '');
+    this.baseURL = (opts.baseURL ?? 'https://x402.acedata.cloud').replace(/\/+$/, '');
     this.platformBaseURL = (opts.platformBaseURL ?? 'https://platform.acedata.cloud').replace(/\/+$/, '');
     this.timeout = opts.timeout ?? 300_000;
     this.maxRetries = opts.maxRetries ?? 2;
@@ -144,7 +156,8 @@ export class Transport {
     let lastError: Error | null = null;
     let paymentAttempted = false;
     let extraHeaders: Record<string, string> = {};
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+    let attempt = 0;
+    while (true) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutMs);
       try {
@@ -158,20 +171,29 @@ export class Transport {
 
         if (resp.status === 402 && this.paymentHandler && !paymentAttempted) {
           const text = await resp.text();
-          let body: PaymentRequiredBody;
+          let body: unknown;
           try {
-            body = JSON.parse(text) as PaymentRequiredBody;
+            body = JSON.parse(text);
           } catch {
             throw mapError(402, { error: { code: 'invalid_402', message: text } });
           }
-          if (!body.accepts?.length) {
+          if (
+            !body ||
+            typeof body !== 'object' ||
+            !Array.isArray((body as PaymentRequiredBody).accepts) ||
+            !(body as PaymentRequiredBody).accepts.length ||
+            !(body as PaymentRequiredBody).accepts.every(
+              (requirement) => requirement !== null && typeof requirement === 'object'
+            )
+          ) {
             throw mapError(402, { error: { code: 'invalid_402', message: 'No payment requirements' } });
           }
+          const paymentRequired = body as PaymentRequiredBody;
           const result = await this.paymentHandler({
             url,
             method,
             body: opts.json,
-            accepts: body.accepts,
+            accepts: paymentRequired.accepts,
           });
           extraHeaders = { ...extraHeaders, ...result.headers };
           paymentAttempted = true;
@@ -186,8 +208,9 @@ export class Transport {
           } catch {
             body = { error: { code: 'unknown', message: text } };
           }
-          if (RETRY_STATUS_CODES.has(resp.status) && attempt < this.maxRetries) {
+          if (!paymentAttempted && RETRY_STATUS_CODES.has(resp.status) && attempt < this.maxRetries) {
             await sleep(backoffDelay(attempt) * 1000);
+            attempt += 1;
             continue;
           }
           throw mapError(resp.status, body);
@@ -197,14 +220,19 @@ export class Transport {
       } catch (err) {
         clearTimeout(timer);
         if (err instanceof APIError) throw err;
-        lastError = err as Error;
-        if (attempt < this.maxRetries) {
+        if (isAbortError(err)) {
+          lastError = timeoutError(err);
+        } else {
+          lastError = err as Error;
+        }
+        if (!paymentAttempted && attempt < this.maxRetries) {
           await sleep(backoffDelay(attempt) * 1000);
+          attempt += 1;
           continue;
         }
+        throw lastError;
       }
     }
-    throw lastError ?? new TransportError('Request failed after retries');
   }
 
   async *requestStream(
@@ -214,52 +242,115 @@ export class Transport {
   ): AsyncGenerator<string, void, unknown> {
     const url = `${this.baseURL}${path}`;
     const headers = { ...this.headers, accept: 'text/event-stream' };
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeout ?? this.timeout);
-
-    try {
-      const resp = await fetch(url, {
-        method,
-        headers,
-        body: opts.json ? JSON.stringify(opts.json) : undefined,
-        signal: controller.signal,
-      });
+    let paymentAttempted = false;
+    let extraHeaders: Record<string, string> = {};
 
-      if (resp.status >= 400) {
-        const text = await resp.text();
-        let body: Record<string, unknown>;
+    while (true) {
+      const controller = new AbortController();
+      const timeoutMs = opts.timeout ?? this.timeout;
+      const connectionTimer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        let resp: Response;
         try {
-          body = JSON.parse(text) as Record<string, unknown>;
-        } catch {
-          body = { error: { code: 'unknown', message: text } };
+          resp = await fetch(url, {
+            method,
+            headers: { ...headers, ...extraHeaders },
+            body: opts.json ? JSON.stringify(opts.json) : undefined,
+            signal: controller.signal,
+          });
+        } catch (error) {
+          if (isAbortError(error)) throw timeoutError(error);
+          throw error;
+        } finally {
+          clearTimeout(connectionTimer);
+        }
+
+        if (resp.status === 402 && this.paymentHandler && !paymentAttempted) {
+          const text = await resp.text();
+          let body: unknown;
+          try {
+            body = JSON.parse(text);
+          } catch {
+            throw mapError(402, { error: { code: 'invalid_402', message: text } });
+          }
+          if (
+            !body ||
+            typeof body !== 'object' ||
+            !Array.isArray((body as PaymentRequiredBody).accepts) ||
+            !(body as PaymentRequiredBody).accepts.length ||
+            !(body as PaymentRequiredBody).accepts.every(
+              (requirement) => requirement !== null && typeof requirement === 'object'
+            )
+          ) {
+            throw mapError(402, { error: { code: 'invalid_402', message: 'No payment requirements' } });
+          }
+          const paymentRequired = body as PaymentRequiredBody;
+          const result = await this.paymentHandler({
+            url,
+            method,
+            body: opts.json,
+            accepts: paymentRequired.accepts,
+          });
+          extraHeaders = { ...extraHeaders, ...result.headers };
+          paymentAttempted = true;
+          continue;
+        }
+
+        if (resp.status >= 400) {
+          const text = await resp.text();
+          let body: Record<string, unknown>;
+          try {
+            body = JSON.parse(text) as Record<string, unknown>;
+          } catch {
+            body = { error: { code: 'unknown', message: text } };
+          }
+          throw mapError(resp.status, body);
         }
-        throw mapError(resp.status, body);
-      }
 
-      if (!resp.body) throw new TransportError('No response body for stream');
+        if (!resp.body) throw new TransportError('No response body for stream');
 
-      const reader = resp.body.getReader();
-      const decoder = new TextDecoder();
-      let buffer = '';
+        const reader = resp.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
 
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
+        try {
+          while (true) {
+            const idleTimer = setTimeout(() => controller.abort(), timeoutMs);
+            let result: Awaited<ReturnType<typeof reader.read>>;
+            try {
+              result = await reader.read();
+            } catch (error) {
+              if (isAbortError(error)) throw timeoutError(error);
+              throw error;
+            } finally {
+              clearTimeout(idleTimer);
+            }
+            const { done, value } = result;
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
 
-        const lines = buffer.split('\n');
-        buffer = lines.pop() ?? '';
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
 
-        for (const line of lines) {
-          if (line.startsWith('data: ')) {
-            const data = line.slice(6);
-            if (data === '[DONE]') return;
-            yield data;
+            for (const line of lines) {
+              if (line.startsWith('data: ')) {
+                const data = line.slice(6);
+                if (data === '[DONE]') return;
+                yield data;
+              }
+            }
+          }
+        } finally {
+          try {
+            await reader.cancel();
+          } catch {
+            // Preserve the original stream error, especially SDK TimeoutError.
           }
         }
+        return;
+      } finally {
+        clearTimeout(connectionTimer);
       }
-    } finally {
-      clearTimeout(timer);
     }
   }
 
@@ -288,12 +379,18 @@ export class Transport {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), opts.timeout ?? this.timeout);
     try {
-      const resp = await fetch(url, {
-        method: 'POST',
-        headers: authHeaders,
-        body,
-        signal: controller.signal,
-      });
+      let resp: Response;
+      try {
+        resp = await fetch(url, {
+          method: 'POST',
+          headers: authHeaders,
+          body,
+          signal: controller.signal,
+        });
+      } catch (error) {
+        if (isAbortError(error)) throw timeoutError(error);
+        throw error;
+      }
       clearTimeout(timer);
 
       if (resp.status >= 400) {