vercel/ai · error · AISDKError

KLINGAI_VIDEO_MISSING_OPTIONS

KLINGAI_VIDEO_MISSING_OPTIONS

Error message

KlingAI Motion Control requires providerOptions.klingai with videoUrl, characterOrientation, and mode.

What it means

KlingAI motion-control video generation is a client-side input validation error: buildMotionControlBody requires the caller to supply providerOptions.klingai.videoUrl, characterOrientation, and mode, and throws before any network call if any are missing. It tells you exactly which provider options the motion-control mode demands.

Source

Thrown at packages/klingai/src/klingai-video-model.ts:735

      });
    }

    this.addPassthroughOptions(body, klingaiOptions);

    return body;
  }

  private buildMotionControlBody(
    options: Parameters<NonNullable<VideoModelV4['doStart']>>[0],
    klingaiOptions: KlingAIVideoModelOptions | undefined,
    warnings: SharedV4Warning[],
  ): Record<string, unknown> {
    if (
      !klingaiOptions?.videoUrl ||
      !klingaiOptions?.characterOrientation ||
      !klingaiOptions?.mode
    ) {
      throw new AISDKError({
        name: 'KLINGAI_VIDEO_MISSING_OPTIONS',
        message:
          'KlingAI Motion Control requires providerOptions.klingai with videoUrl, characterOrientation, and mode.',
      });
    }

    const mode = 'motion-control' as const;
    const body: Record<string, unknown> = {
      model_name: getApiModelName(this.modelId, mode),
      video_url: klingaiOptions.videoUrl,
      character_orientation: klingaiOptions.characterOrientation,
      mode: klingaiOptions.mode,
    };

    if (options.prompt != null) {
      body.prompt = options.prompt;
    }

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Add providerOptions.klingai with videoUrl (reference video URL), characterOrientation, and mode
2. Double-check key spellings and casing against the @ai-sdk/klingai docs
3. Confirm you are on a KlingAI model/endpoint that supports motion control

Example fix

// before
await model.doGenerate({ prompt: 'dance like the reference' });
// after
await model.doGenerate({
  prompt: 'dance like the reference',
  providerOptions: {
    klingai: {
      videoUrl: 'https://example.com/ref.mp4',
      characterOrientation: 'front',
      mode: 'standard',
    },
  },
});

const klingai = providerOptions?.klingai;
if (!klingai?.videoUrl || !klingai?.characterOrientation || !klingai?.mode) {
  throw new Error('Motion control requires klingai.videoUrl, characterOrientation, and mode');
}

function hasMotionControlOptions(o: unknown): o is {
  videoUrl: string; characterOrientation: string; mode: string;
} {
  const k = o as any;
  return !!k && typeof k.videoUrl === 'string' &&
    typeof k.characterOrientation === 'string' && typeof k.mode === 'string';
}

try {
  await model.doGenerate({ prompt, providerOptions });
} catch (e) {
  if (AISDKError.isInstance(e) && e.name === 'KLINGAI_VIDEO_MISSING_OPTIONS') {
    // fix providerOptions.klingai before retrying
  } else throw e;
}

When it happens

Trigger: Calling the KlingAI video model with a motion-control prompt/mode while providerOptions.klingai is missing videoUrl, characterOrientation, or mode (or providerOptions.klingai itself is absent).

Common situations: Copy-pasting a basic text-to-video call and switching to motion control without adding options, misspelling a key (e.g. videoURL), or forgetting providerOptions entirely.

Related errors

• Invalid n: expected a positive integer, received ${JSON.stri
• Video model ${model.modelId} supports at most ${knownMaxVide
• providerOptions.elevenlabs.streaming.filterBackgroundAudio c
• providerOptions.xai.channels is required when providerOption
• maxEmbeddingsPerCall must be greater than 0

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/b69654bb5f45e39b. Report an issue: GitHub.