Skip to main content

Doubao

The @aigne/doubao package provides a seamless integration between the AIGNE Framework and Doubao's powerful language and image generation models. This guide provides a complete reference for configuring and utilizing Doubao models within your AIGNE applications.

This integration allows developers to leverage Doubao's advanced AI capabilities through the consistent and unified interface of the AIGNE Framework.

Installation

To begin, install the necessary packages using your preferred package manager. You will need both @aigne/core and the Doubao-specific package.

bash
npm install @aigne/doubao @aigne/core
bash
yarn add @aigne/doubao @aigne/core
bash
pnpm add @aigne/doubao @aigne/core

Configuration

To use the Doubao models, you must provide an API key. The key can be configured in one of two ways, in order of precedence:

  1. Direct Instantiation

    Pass the apiKey directly in the model's constructor. This method is explicit and overrides any other configuration.

  2. Environment Variable

    Set the DOUBAO_API_KEY environment variable. The model will automatically use this variable if no key is provided in the constructor.

"Configuration Example"

typescript
import { DoubaoChatModel } from "@aigne/doubao";

// Method 1: Direct Instantiation
const modelWithApiKey = new DoubaoChatModel({
  apiKey: "your-doubao-api-key",
});

// Method 2: Environment Variable
// Set DOUBAO_API_KEY in your .env file or shell
// DOUBAO_API_KEY="your-doubao-api-key"
const modelFromEnv = new DoubaoChatModel();

The base URL for the Doubao API is pre-configured to https://ark.cn-beijing.volces.com/api/v3, but it can be overridden by passing a baseURL option to the constructor if necessary.

Chat Models

For conversational tasks, the DoubaoChatModel provides an interface to Doubao's language models. It leverages an OpenAI-compatible API structure, ensuring a familiar development experience.

Basic Usage

To perform a chat completion, instantiate DoubaoChatModel and use the invoke method.

"Basic Chat Completion"

typescript
import { DoubaoChatModel } from "@aigne/doubao";

const model = new DoubaoChatModel({
  apiKey: "your-doubao-api-key", // Or use environment variable
  model: "doubao-seed-1-6-250615",
  modelOptions: {
    temperature: 0.7,
  },
});

const result = await model.invoke({
  messages: [{ role: "user", content: "Introduce yourself" }],
});

console.log(result);

Example Response

json
{
  "text": "Hello! I'm an AI assistant powered by Doubao's language model.",
  "model": "doubao-seed-1-6-250615",
  "usage": {
    "inputTokens": 7,
    "outputTokens": 12
  }
}

Streaming Responses

For real-time applications, you can stream the response from the model. Set the streaming option to true in the invoke call and iterate over the resulting stream to process chunks as they arrive.

"Streaming Chat Response"

typescript
import { isAgentResponseDelta } from "@aigne/core";
import { DoubaoChatModel } from "@aigne/doubao";

const model = new DoubaoChatModel({
  apiKey: "your-doubao-api-key",
  model: "doubao-seed-1-6-250615",
});

const stream = await model.invoke(
  {
    messages: [{ role: "user", content: "Introduce yourself" }],
  },
  { streaming: true }
);

let fullText = "";
const json = {};

for await (const chunk of stream) {
  if (isAgentResponseDelta(chunk)) {
    const text = chunk.delta.text?.text;
    if (text) {
      fullText += text;
      process.stdout.write(text); // Print text chunks as they arrive
    }
    if (chunk.delta.json) {
      Object.assign(json, chunk.delta.json);
    }
  }
}

console.log("\n--- Final Data ---");
console.log(fullText);
console.log(json);

Chat Model Parameters

The DoubaoChatModel constructor accepts the following options:

  • apiKey string — Your Doubao API key. If not provided, the DOUBAO_API_KEY environment variable will be used.
  • model string (default: doubao-seed-1-6-250615) — The specific chat model to use.
  • baseURL string (default: https://ark.cn-beijing.volces.com/api/v3) — The base URL for the Doubao API endpoint.
  • modelOptions object — Additional options passed to the model API, such as temperature, top_p, etc. These are standard OpenAI-compatible parameters.

Image Models

The DoubaoImageModel class enables image generation by interfacing with Doubao's image models.

Basic Usage

Instantiate DoubaoImageModel and call the invoke method with a prompt to generate an image.

"Image Generation"

typescript
import { DoubaoImageModel } from "@aigne/doubao";

async function generateImage() {
  const imageModel = new DoubaoImageModel({
    apiKey: "your-doubao-api-key", // Or use environment variable
    model: "doubao-seedream-4-0-250828",
  });

  const result = await imageModel.invoke({
    prompt: "A photorealistic image of a cat programming on a laptop",
    modelOptions: {
      size: "1024x1024",
      watermark: false,
    },
  });

  console.log(result);
}

generateImage();

Example Response

json
{
  "images": [
    {
      "type": "file",
      "data": "...", // base64 encoded image data
      "mimeType": "image/jpeg"
    }
  ],
  "usage": {
    "inputTokens": 0,
    "outputTokens": 1
  },
  "model": "doubao-seedream-4-0-250828"
}

Image Model Parameters

The DoubaoImageModel invoke method accepts an input object with the following properties. Note that parameter availability may vary by model.

  • prompt string (required) — A text description of the desired image(s).
  • model string (default: doubao-seedream-4-0-250828) — The identifier for the image model to use.
  • image FileUnion — For image-to-image models (doubao-seededit-3-0-i2i), provides the input image.
  • modelOptions object — An object containing model-specific parameters.
    • size string — The desired dimensions of the generated image (e.g., "1024x1024").
    • seed number — A seed value for reproducible results. Supported by doubao-seedream-3-0-t2i and doubao-seededit-3-0-i2i.
    • guidanceScale number — Controls how closely the generated image follows the prompt. Supported by doubao-seedream-3-0-t2i and doubao-seededit-3-0-i2i.
    • stream boolean (default: false) — If true, streams the generation results. Supported by doubao-seedream-4 models.
    • watermark boolean (default: false) — If false, disables the watermark on the generated image.
    • sequentialImageGeneration boolean — Enables sequential image generation. Supported by doubao-seedream-4 models.

Supported Image Models

The following table lists the supported image models and their key characteristics.

Model FamilySupported ModelsKey Use Case
doubao-seedream-4doubao-seedream-4-0-250828Text-to-Image (T2I)
doubao-seedream-3-0-t2i(Specific model names vary)Text-to-Image (T2I)
doubao-seededit-3-0-i2i(Specific model names vary)Image-to-Image (I2I)