# ReAIVisionAPI

## 安装

```bash
npm i @re-ai/openai-like-api
```

## 支持的服务

目前支持以下文生图服务：

| 服务 | API Key 格式 | 特点 |
|------|-------------|------|
| OpenAI | `sk-xxx` | DALL-E 3 支持 |
| 智谱AI | `zhipu:xxx` | GLM-4 支持 |
| Flux.1 | `flux:xxx:xxx` | 高质量图像生成 |
| 百度云 | `baidu:xxx:xxx` | 文心一言支持 |
| 腾讯混元 | `hunyuan:xxx:xxx` | 多样风格支持 |
| 通义万象 | `dashscope:xxx` | 阿里云服务 |
| 豆包 | `doubao:xxx` | 高质量艺术图像 |

## 基础用法

```typescript
import { ReAIVisionAPI } from "@re-ai/openai-like-api";

const api = ReAIVisionAPI({
    apiKey: "doubao:your_api_key" // 根据服务选择对应的 API Key 格式
});

// 生成图片
api.image({
    prompt: "一只可爱的猫咪",
    model_version: "general_v2.1_L",  // 豆包模型版本
    req_key: "high_aes_general_v21_L" // 豆包请求类型
}).then(async res => {
    for await (const item of res) {
        if (item.status === "completed" && item.data) {
            console.log("生成的图片URLs:", item.data.image_urls);
            console.log("Base64图片数据:", item.data.binary_data_base64);
        }
    }
});

## 参数说明

### 通用参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | string | 是 | 图片生成提示词 |
| width | number | 否 | 图片宽度 |
| height | number | 否 | 图片高度 |
| resolution | string | 否 | 图片分辨率，如 "1024x1024" |

### 豆包特有参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| model_version | string | 是 | 模型版本，如 "general_v2.1_L" |
| req_key | string | 是 | 请求类型，如 "high_aes_general_v21_L" |
| req_schedule_conf | string | 否 | 生成模式，可选值：<br>- general_v20_9B_pe（美感版，默认）<br>- general_v20_9B_rephraser（标准版） |
| seed | number | 否 | 随机种子，-1为随机（默认），正整数时相同参数会生成相似结果 |
| scale | number | 否 | 文本描述影响程度，范围[1, 10]，默认3.5 |
| ddim_steps | number | 否 | 生成步数，范围[1, 50]，默认25 |
| use_pre_llm | boolean | 否 | 是否开启文本扩写优化，默认true |
| use_sr | boolean | 否 | 是否开启超分辨率，默认true |
| logo_info | object | 否 | 水印配置，包含：<br>- add_logo: 是否添加水印<br>- position: 位置(0-3)<br>- language: 语言(0中/1英)<br>- opacity: 透明度(0-1)<br>- logo_text_content: 水印文本 |

## 返回值格式

生成结果以流的形式返回，每个结果项包含以下字段：

```typescript
interface ImageResult {
    status: "processing" | "completed" | "failed";
    message?: string;       // 错误信息（如果失败）
    created_at?: number;    // 创建时间戳
    data?: {
        format: "url" | "b64_json";
        url?: string;                  // 单个URL响应
        b64_json?: string;            // 单个base64响应
        image_urls?: string[];        // 多个URL响应
        binary_data_base64?: string[]; // 多个base64响应
    };
}
```

## 错误处理

豆包API可能返回以下错误码：

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 50411 | 输入图片风险检查失败 | 检查输入图片是否包含敏感内容 |
| 50511 | 输出图片风险检查失败 | 调整生成参数或提示词 |
| 50412 | 输入文本风险检查失败 | 检查提示词是否包含敏感内容 |
| 50512 | 输出文本风险检查失败 | 调整生成参数或提示词 |
| 50413 | 输入文本被NER/IP/黑名单拦截 | 检查提示词是否包含受限内容 |

错误处理示例：

```typescript
api.image({
    prompt: "一只可爱的猫咪",
    model_version: "general_v2.1_L",
    req_key: "high_aes_general_v21_L"
}).then(async res => {
    try {
        for await (const item of res) {
            if (item.status === "failed") {
                console.error("生成失败:", item.message);
                break;
            }
            if (item.status === "completed" && item.data) {
                console.log("生成成功 - URLs:", item.data.image_urls);
            }
        }
    } catch (error) {
        console.error("API调用错误:", error);
    }
});

### 豆包（Doubao）

豆包API提供高质量的艺术图像生成服务，特点包括：

- 支持多种艺术风格和生成模式（标准版/美感版）
- 高质量图像输出（最高768x768，支持超分辨率）
- 实时生成进度反馈
- 支持批量生成
- 灵活的水印配置
- 提供文本扩写优化
- 支持随机种子控制，可重复生成相似结果

认证配置：
```typescript
// API密钥格式：doubao:AccessKeyId:SecretKey
// AccessKeyId: 火山引擎访问密钥ID
// SecretKey: 火山引擎访问密钥
const api = ReAIVisionAPI({ apiKey: "doubao:your_access_key_id:your_secret_key" });
```

配置示例：
```typescript
api.image({
    prompt: "水墨画风格的山水",
    model_version: "general_v2.1_L",
    req_key: "high_aes_general_v21_L",
    width: 1024,
    height: 1024
}).then(async res => {
    for await (const item of res) {
        console.log(item);
    }
});
```

更多服务的详细说明和示例代码请参考各服务商的官方文档。