Alibaba

Alibaba Cloud Model Studio provides access to the Qwen model series, including advanced reasoning capabilities.

API keys can be obtained from the Console.

Setup

The Alibaba provider is available via the @ai-sdk/alibaba module. You can install it with:

$ pnpm add @ai-sdk/alibaba

$ npm install @ai-sdk/alibaba

$ yarn add @ai-sdk/alibaba

$ bun add @ai-sdk/alibaba

Provider Instance

You can import the default provider instance alibaba from @ai-sdk/alibaba:

import { alibaba } from '@ai-sdk/alibaba';

For custom configuration, you can import createAlibaba and create a provider instance with your settings:

import { createAlibaba } from '@ai-sdk/alibaba';

const alibaba = createAlibaba({
  apiKey: process.env.ALIBABA_API_KEY ?? '',
});

You can use the following optional settings to customize the Alibaba provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers or regional endpoints. The default prefix is https://dashscope-intl.aliyuncs.com/compatible-mode/v1.

• videoBaseURL string

  Use a different URL prefix for video generation API calls. The video API uses the DashScope native endpoint (not the OpenAI-compatible endpoint). The default prefix is https://dashscope-intl.aliyuncs.com.

• embeddingBaseURL string

  Use a different URL prefix for embedding API calls. The embedding API uses the DashScope native endpoint (not the OpenAI-compatible endpoint). The default prefix is https://dashscope-intl.aliyuncs.com/api/v1.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the ALIBABA_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation.

• includeUsage boolean

  Include usage information in streaming responses. When enabled, token usage will be included in the final chunk. Defaults to true.

Language Models

You can create language models using a provider instance:

import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const { text } = await generateText({
  model: alibaba('qwen-plus'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

You can also use the .chatModel() or .languageModel() factory methods:

const model = alibaba.chatModel('qwen-plus');
// or
const model = alibaba.languageModel('qwen-plus');

Alibaba language models can be used in the streamText function (see AI SDK Core).

The following optional provider options are available for Alibaba models:

• enableThinking boolean

  Enable thinking/reasoning mode for supported models. When enabled, the model generates reasoning content before the response. Defaults to false.

• thinkingBudget number

  Maximum number of reasoning tokens to generate. Limits the length of thinking content.

• preserveThinking boolean

  Preserve reasoning from previous assistant messages for supported models. When enabled, reasoning is sent separately as Alibaba reasoning_content and preserve_thinking is enabled. Defaults to true for models that support preserved thinking; set to false to opt out. Append AI SDK responseMessages unchanged when continuing the conversation. See Alibaba's preserved-thinking documentation for the list of supported models.

• parallelToolCalls boolean

  Whether to enable parallel function calling during tool use. Defaults to true.

Thinking Mode

Alibaba's Qwen models support thinking/reasoning mode for complex problem-solving:

import { alibaba, type AlibabaLanguageModelChatOptions } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const { text, reasoning } = await generateText({
  model: alibaba('qwen3-max'),
  providerOptions: {
    alibaba: {
      enableThinking: true,
      thinkingBudget: 2048,
    } satisfies AlibabaLanguageModelChatOptions,
  },
  prompt: 'How many "r"s are in the word "strawberry"?',
});

console.log('Reasoning:', reasoning);
console.log('Answer:', text);

For models that are thinking-only (like qwen3-235b-a22b-thinking-2507), thinking mode is enabled by default.

Preserved Thinking in Multi-Turn Conversations

For models that support preserved thinking, the AI SDK replays reasoning from previous assistant messages as Alibaba reasoning_content by default, so the model can build on its earlier thought process:

import { alibaba, type AlibabaLanguageModelChatOptions } from '@ai-sdk/alibaba';
import { generateText, type ModelMessage } from 'ai';

const providerOptions = {
  alibaba: {
    enableThinking: true,
    thinkingBudget: 2048,
  } satisfies AlibabaLanguageModelChatOptions,
};

const opening: ModelMessage = {
  role: 'user',
  content: 'Is Kafka or RocketMQ a better fit for transactional messages?',
};

const first = await generateText({
  model: alibaba('qwen3.7-max'),
  messages: [opening],
  providerOptions,
});

const second = await generateText({
  model: alibaba('qwen3.7-max'),
  messages: [
    opening,
    ...first.responseMessages, // append unchanged to keep the reasoning parts
    { role: 'user', content: 'Which tradeoff mattered most?' },
  ],
  providerOptions,
});

When continuing the conversation, append responseMessages unchanged. If you rebuild assistant history from visible text only, the reasoning parts are discarded before the provider can serialize them as reasoning_content. Set preserveThinking: false to opt out of replay, and note the following caveats:

• preserveThinking does not enable thinking by itself. Pair it with enableThinking/thinkingBudget or the top-level reasoning option.
• It is enabled by default only for models that Alibaba documents as supporting preserved thinking; for other models, preserve_thinking is not sent unless you set the option explicitly. See Alibaba's preserved-thinking documentation for the current list of supported models.
• Reasoning from the current tool-call round (after the last user message) is always sent back with tool results, as Alibaba recommends; the option only controls reasoning from earlier rounds.
• Preserved reasoning increases input token usage and billing.
• Historical reasoning remains separate from visible assistant text; it is never merged into content.

Tool Calling

Alibaba models support tool calling with parallel execution:

import { alibaba } from '@ai-sdk/alibaba';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text } = await generateText({
  model: alibaba('qwen-plus'),
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      inputSchema: z.object({
        location: z.string().describe('The location to get the weather for'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10,
      }),
    }),
  },
  prompt: 'What is the weather in San Francisco?',
});

Prompt Caching

Alibaba supports both implicit and explicit prompt caching to reduce costs for repeated prompts.

Implicit caching works automatically - the provider caches appropriate content without any configuration. For more control, you can use explicit caching by marking specific messages with cacheControl:

Single message cache control

import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const { text, usage } = await generateText({
  model: alibaba('qwen-plus'),
  messages: [
    {
      role: 'system',
      content: 'You are a helpful assistant. [... long system prompt ...]',
      providerOptions: {
        alibaba: {
          cacheControl: { type: 'ephemeral' },
        },
      },
    },
  ],
});

Multi-part message cache control

import { alibaba } from '@ai-sdk/alibaba';
import { generateText } from 'ai';

const longDocument = '... large document content ...';

const { text, usage } = await generateText({
  model: alibaba('qwen-plus'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Context: Please analyze this document.',
        },
        {
          type: 'text',
          text: longDocument,
          providerOptions: {
            alibaba: {
              cacheControl: { type: 'ephemeral' },
            },
          },
        },
      ],
    },
  ],
});

Note: The minimum content length for a cache block is 1,024 tokens.

Embedding Models

You can create text embedding models using the .embedding() factory method. For more on embeddings with the AI SDK see embed() and embedMany().

const model = alibaba.embedding('text-embedding-v4');

You can use Alibaba embedding models to generate embeddings with the embed function:

import { alibaba, type AlibabaEmbeddingModelOptions } from '@ai-sdk/alibaba';
import { embed } from 'ai';

const { embedding, usage } = await embed({
  model: alibaba.embedding('text-embedding-v4'),
  value: 'sunny day at the beach',
  providerOptions: {
    alibaba: {
      textType: 'document',
      dimension: 1024,
      outputType: 'dense',
    } satisfies AlibabaEmbeddingModelOptions,
  },
});

Use embedMany to embed multiple text values. Alibaba text embedding models support up to 10 values per API call; larger batches are split automatically by embedMany.

import { alibaba, type AlibabaEmbeddingModelOptions } from '@ai-sdk/alibaba';
import { embedMany } from 'ai';

const { embeddings } = await embedMany({
  model: alibaba.embedding('text-embedding-v4'),
  values: [
    'sunny day at the beach',
    'rainy afternoon in the city',
    'snowy night in the mountains',
  ],
  providerOptions: {
    alibaba: {
      textType: 'document',
      dimension: 1024,
    } satisfies AlibabaEmbeddingModelOptions,
  },
});

Alibaba embedding models support additional provider options that can be passed via providerOptions.alibaba:

• textType 'query' | 'document'

  Differentiates query text from document text for asymmetric retrieval tasks. Defaults to document.

• dimension number

  The dimension of the output embedding vectors. Defaults to 1024. text-embedding-v4 also supports 1536 and 2048 dimensions.

• outputType 'dense' | 'sparse' | 'dense&sparse'

  Specifies the output vector type. Defaults to dense. The AI SDK embedding interface returns dense number[] vectors, so sparse-only output is not supported and will throw. Use dense&sparse to receive dense embeddings in embedding/embeddings and sparse vectors in providerMetadata.alibaba.sparseEmbeddings.

Embedding Model Capabilities

Video Models

You can create Wan video models that call the Alibaba Cloud DashScope API using the .video() factory method. For more on video generation with the AI SDK see generateVideo().

Alibaba supports three video generation modes: text-to-video, image-to-video (first frame), and reference-to-video.

Text-to-Video

Generate videos from text prompts:

import { alibaba, type AlibabaVideoModelOptions } from '@ai-sdk/alibaba';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: alibaba.video('wan2.6-t2v'),
  prompt: 'A serene mountain lake at sunset with gentle ripples on the water.',
  resolution: '1280x720',
  duration: 5,
  providerOptions: {
    alibaba: {
      promptExtend: true,
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies AlibabaVideoModelOptions,
  },
});

wan2.7 models additionally support the aspectRatio option (mapped to the API's ratio parameter) and always generate audio. Multi-shot structure is described directly in the prompt instead of the shotType option:

const { video } = await generateVideo({
  model: alibaba.video('wan2.7-t2v'),
  prompt:
    'A serene mountain lake at sunset. The camera pans across the water, then cuts to a close-up of ripples catching the light.',
  resolution: '1920x1080',
  aspectRatio: '16:9',
  duration: 5,
});

Image-to-Video

Generate videos from a first-frame image and optional text prompt:

import { alibaba, type AlibabaVideoModelOptions } from '@ai-sdk/alibaba';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: alibaba.video('wan2.6-i2v'),
  prompt: {
    image: 'https://example.com/landscape.jpg',
    text: 'Camera slowly pans across the landscape',
  },
  duration: 5,
  providerOptions: {
    alibaba: {
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies AlibabaVideoModelOptions,
  },
});

You can also pass the first frame using the top-level frameImages option:

import { alibaba, type AlibabaVideoModelOptions } from '@ai-sdk/alibaba';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: alibaba.video('wan2.6-i2v'),
  prompt: 'Camera slowly pans across the landscape',
  frameImages: [
    {
      image: 'https://example.com/landscape.jpg',
      frameType: 'first_frame',
    },
  ],
  duration: 5,
  providerOptions: {
    alibaba: {
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies AlibabaVideoModelOptions,
  },
});

Reference-to-Video

Generate videos using reference images and/or videos for character consistency.

For wan2.6 models, use character identifiers (character1, character2, etc.) in your prompt to reference them. References must be public URLs:

import { alibaba, type AlibabaVideoModelOptions } from '@ai-sdk/alibaba';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: alibaba.video('wan2.6-r2v-flash'),
  prompt: 'character1 walks through a beautiful garden and waves at the camera',
  resolution: '1280x720',
  duration: 5,
  inputReferences: ['https://example.com/character-reference.jpg'],
  providerOptions: {
    alibaba: {
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies AlibabaVideoModelOptions,
  },
});

For wan2.7 models, use Image 1, Image 2, Video 1, etc. in your prompt (images and videos are counted separately, in reference order). Image references can be public URLs or inline file data; video references must be public URLs:

import { alibaba, type AlibabaVideoModelOptions } from '@ai-sdk/alibaba';
import { experimental_generateVideo as generateVideo } from 'ai';
import { readFile } from 'node:fs/promises';

const imageBytes = await readFile('./character.png');

const { video } = await generateVideo({
  model: alibaba.video('wan2.7-r2v'),
  prompt: 'Image 1 walks through the scene shown in Image 2.',
  resolution: '1920x1080',
  duration: 5,
  inputReferences: [
    imageBytes, // inline image data, sent as base64 data URI
    'https://example.com/background.png',
  ],
  providerOptions: {
    alibaba: {
      ratio: '16:9',
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies AlibabaVideoModelOptions,
  },
});

For full control over the wan2.7 media array (e.g. voice references or explicit media types), use the media provider option, which overrides the automatic mapping from inputReferences and frameImages:

const { video } = await generateVideo({
  model: alibaba.video('wan2.7-r2v'),
  prompt: 'Video 1 walks into the room. Image 1 looks up and says hello.',
  providerOptions: {
    alibaba: {
      media: [
        {
          type: 'reference_video',
          url: 'https://example.com/character.mp4',
          referenceVoice: 'https://example.com/voice.mp3',
        },
        { type: 'reference_image', url: 'https://example.com/scene.png' },
        { type: 'first_frame', url: 'https://example.com/opening-frame.png' },
      ],
    } satisfies AlibabaVideoModelOptions,
  },
});

Video Provider Options

The following provider options are available via providerOptions.alibaba:

• negativePrompt string

  A description of what to avoid in the generated video (max 500 characters).

• audioUrl string

  URL to an audio file for audio-video sync (WAV/MP3, 3-30 seconds, max 15MB).

• promptExtend boolean

  Enable prompt extension/rewriting for better generation quality. Defaults to true.

• shotType 'single' | 'multi'

  Shot type for video generation. 'multi' enables multi-shot cinematic narrative (wan2.6 models only).

• watermark boolean

  Whether to add a watermark to the generated video. Defaults to false.

• audio boolean

  Whether to generate audio (for wan2.6 I2V and R2V models; wan2.7 models always generate audio).

• referenceUrls string[]

  Array of reference image/video URLs for reference-to-video mode (wan2.6 models). Supports 0-5 images and 0-3 videos, max 5 total. Prefer the top-level inputReferences option when passing reference images.

• media Array<{ type, url, referenceVoice? }>

  Explicit media array for reference-to-video mode (wan2.7 models). Each item has a type ('reference_image', 'reference_video', or 'first_frame'), a url (public URL, or a data:{mime};base64,{data} URI for images), and an optional referenceVoice audio URL. Overrides the automatic mapping from inputReferences and frameImages.

• ratio '16:9' | '9:16' | '1:1' | '4:3' | '3:4'

  Aspect ratio (wan2.7 text-to-video and reference-to-video models). The top-level aspectRatio option is mapped to this parameter automatically.

• pollIntervalMs number

  Polling interval in milliseconds for checking task status. Defaults to 5000.

• pollTimeoutMs number

  Maximum wait time in milliseconds for video generation. Defaults to 600000 (10 minutes).

Video Model Capabilities

Text-to-Video

Image-to-Video (First Frame)

Reference-to-Video

Model Capabilities

Please see the Alibaba Cloud Model Studio docs for a full list of available models. You can also pass any available provider model ID as a string if needed.