手抄报系统 DMXAPI 图片生成服务对接文档

手抄报系统 DMXAPI 图片生成服务对接文档

一、概述

本文档详细介绍手抄报系统如何对接 DMXAPI 图片生成服务，实现 AI 生成手抄报彩色稿图的功能。

1.1 DMXAPI 简介

DMXAPI 是一个国内 AI API 服务平台，提供多种图片生成模型：

模型	特点	分辨率	适用场景
Gemini 2.5 Flash Image	速度快，成本低	1K	快速预览、常规生成
豆包即梦 Seedream 4.0	画质高，细节丰富	2K	高质量输出、正式使用

1.2 对接架构

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   前端页面   │ ──▶ │   后端API    │ ──▶ │   DMXAPI 服务    │
│  Generate   │     │  generate.js │     │  (Gemini/Seedream)│
└─────────────┘     └─────────────┘     └─────────────────┘
                          │
                          ▼
                    ┌─────────────────┐
                    │   图片处理服务   │
                    │ outlineExtractor │
                    │  (Sharp线稿提取) │
                    └─────────────────┘

---

二、环境配置

2.1 获取 API Key

1. 访问 DMXAPI 官网 注册账号
2. 在控制台获取 API Key
3. 根据需要选择开通相应模型服务

2.2 配置环境变量

在 backend/.env 文件中添加：

# DMXAPI 配置
DMXAPI_API_KEY=your_dmxapi_api_key_here
DMXAPI_MODEL=gemini-2.5-flash-image  # 默认模型
# DMXAPI_API_URL=https://www.dmxapi.cn/v1/images/generations  # 可选，自定义API地址

2.3 模型选择说明

环境变量值	对应模型	API 端点
gemini-2.5-flash-image	Gemini 2.5 Flash Image	https://www.dmxapi.cn/v1beta/models/gemini-2.5-flash-image:generateContent
doubao-seedream-4-0-250828	豆包即梦 Seedream 4.0	https://www.dmxapi.cn/v1/images/generations

---

三、服务实现

3.1 Provider 核心代码

文件：backend/src/services/providers/dmxapiProvider.js

const axios = require('axios');

class DMXAPIProvider {
  constructor() {
    this.apiKey = process.env.DMXAPI_API_KEY;
    this.model = process.env.DMXAPI_MODEL || 'gemini-2.5-flash-image';

    // 检测模型类型
    this.isGeminiModel = this.model.includes('gemini') || this.model.includes('Gemini');

    // 根据模型类型设置不同的 API URL
    if (this.isGeminiModel) {
      this.apiUrl = 'https://www.dmxapi.cn/v1beta/models/gemini-2.5-flash-image:generateContent';
      this.modelDisplayName = 'Gemini 2.5 Flash Image';
    } else {
      this.apiUrl = process.env.DMXAPI_API_URL || 'https://www.dmxapi.cn/v1/images/generations';
      this.modelDisplayName = '豆包即梦 Seedream 4.0';
    }

    this.isConfigured = !!this.apiKey;
  }
}

module.exports = new DMXAPIProvider();

3.2 Gemini 模型调用

async generateWithGemini(prompt) {
  const requestData = {
    contents: [{
      parts: [{ text: prompt }]
    }],
    generationConfig: {
      imageConfig: {
        aspectRatio: '1:1'  // 可配置宽高比
      }
    }
  };

  const response = await axios.post(this.apiUrl, requestData, {
    headers: {
      'x-goog-api-key': this.apiKey,
      'Content-Type': 'application/json'
    },
    timeout: 120000
  });

  // 从响应中提取 Base64 图片数据
  const imageData = response.data.candidates[0].content.parts[0].inlineData.data;
  const imageBuffer = Buffer.from(imageData, 'base64');

  return {
    buffer: imageBuffer,
    provider: 'dmxapi',
    model: this.model
  };
}

请求格式说明：

• Gemini 模型使用 x-goog-api-key 请求头
• 返回图片为 Base64 编码格式

3.3 Seedream 模型调用

async generateWithSeedream(prompt, options = {}) {
  const requestData = {
    model: 'doubao-seedream-4-0-250828',
    prompt: prompt,
    size: options.size || '2K',  // 1K 或 2K
    response_format: 'url',      // 返回URL格式
    watermark: false
  };

  const response = await axios.post(
    'https://www.dmxapi.cn/v1/images/generations',
    requestData,
    {
      headers: {
        'Authorization': this.apiKey,
        'Content-Type': 'application/json'
      },
      timeout: 120000
    }
  );

  // 返回图片URL，需要下载
  const imageUrl = response.data.data[0].url;
  const imageResponse = await axios.get(imageUrl, { responseType: 'arraybuffer' });
  const imageBuffer = Buffer.from(imageResponse.data);

  return {
    buffer: imageBuffer,
    provider: 'dmxapi',
    model: 'doubao-seedream-4-0-250828',
    imageUrl: imageUrl
  };
}

请求格式说明：

• Seedream 模型使用 Authorization: Bearer <API_KEY> 请求头
• 返回图片为 URL 格式，需要额外下载步骤

---

四、后端路由集成

4.1 图片生成路由

文件：backend/src/routes/generate.js

router.post('/generate-image', async (req, res) => {
  const { theme, prompt, newspaperId, provider, model } = req.body;

  // 使用图片生成服务
  const imageBuffer = await imageGenerationService.generateImage(prompt, {
    provider: provider,
    model: model
  });

  // 上传到七牛云 OSS
  const uploadResult = await qiniuService.uploadColoredImage(
    imageBuffer.buffer,
    newspaperId
  );

  // 自动生成线稿
  const outlineResult = await generateOutlines(uploadResult.url, newspaperId);

  // 返回结果
  res.json({
    success: true,
    data: {
      colored_image_url: uploadResult.url,
      dark_outline_image_url: outlineResult.darkOutlineUrl,
      light_outline_image_url: outlineResult.lightOutlineUrl,
      model: imageBuffer.model
    }
  });
});

4.2 前端调用示例

文件：admin-panel/src/views/Newspapers.vue

const handleGenerateImage = async () => {
  const requestData = {
    theme: generateForm.value.theme,
    prompt: generateForm.value.prompt,
    newspaperId: generateForm.value.newspaperId || undefined
  };

  // 根据选择的模型设置参数
  if (generateForm.value.provider === 'dmxapi-gemini') {
    requestData.provider = 'dmxapi';
    requestData.model = 'gemini-2.5-flash-image';
  } else if (generateForm.value.provider === 'dmxapi-seedream') {
    requestData.provider = 'dmxapi';
    requestData.model = 'doubao-seedream-4-0-250828';
  }

  const result = await generateImage(requestData);

  if (result.success) {
    ElMessage.success('生成成功！');
    generatedImage.value = result.data.colored_image_url;
  }
};

---

五、模型对比

特性	Gemini 2.5 Flash Image	豆包即梦 Seedream 4.0
API 端点	/v1beta/models/...:generateContent	/v1/images/generations
认证方式	x-goog-api-key Header	Authorization: Bearer Header
返回格式	Base64 直接返回	URL，需二次下载
分辨率	1K	2K（更高清）
生成速度	更快	适中
成本	较低	适中
推荐场景	预览、快速生成	正式输出、高质量需求

---

六、错误处理

6.1 常见错误码

if (error.response) {
  const { status, data } = error.response;

  if (status === 429) {
    throw new Error('DMXAPI 配额已用尽或超出限制');
  }

  if (status === 401) {
    throw new Error('DMXAPI API Key 无效');
  }

  if (data && data.error) {
    throw new Error(`DMXAPI 错误: ${data.error.message}`);
  }
}

6.2 错误对照表

HTTP 状态码	错误原因	解决方案
400	请求参数错误	检查 prompt 格式和长度
401	API Key 无效	检查 DMXAPI_API_KEY 配置
403	无权限访问	确认模型已开通
429	请求频率超限	降低请求频率或升级套餐
500	服务器内部错误	联系 DMXAPI 客服

---

七、最佳实践

7.1 Prompt 优化建议

// 好的 Prompt 示例
const prompt = `
创建一个手抄报模板，主题：安全教育
要求：
- 包含标题区域和内容区域
- 使用简洁的线条设计
- 适合儿童手绘上色
- 画面清晰，线条分明
`;

// 避免的 Prompt
const badPrompt = `画个手抄报`;  // 太简单，生成效果不佳

7.2 请求超时配置

// 推荐超时时间
const timeout = 120000;  // 120秒，适合图片生成

axios.post(url, data, {
  timeout: timeout,
  headers: { /* ... */ }
});

7.3 图片后处理

生成后的图片会自动进行线稿提取：

// 提取两种线稿
const { darkOutlineUrl, lightOutlineUrl } = await generateOutlines(
  coloredImageUrl,
  newspaperId
);

// 深色线稿：sigma=12, opacity=1.0  → 直接涂色
// 浅色线稿：sigma=35, opacity=0.3  → 先描边再涂色

---

八、相关资源

• DMXAPI 官网: https://www.dmxapi.cn/
• API 文档: https://www.dmxapi.cn/docs
• 价格说明: https://www.dmxapi.cn/pricing
• 手抄报系统源码: https://github.com/your-repo/handwritten-newspaper

---

九、更新日志

日期	版本	更新内容
2024-04-23	v1.0	初始版本，支持 Gemini 和 Seedream 双模型
2024-04-21	v1.1	新增线稿自动提取功能
2024-03-15	v1.0	首次对接 DMXAPI

---

本文档由 CodeBuddy AI 助手生成，如有问题请联系开发者。