# API 参考文档

## 概述

本技能使用两套 API：
1. **Lyra Flash API** - 用于图像生成和编辑（文生图、图生图）
2. **Qwen2.5-VL API** - 用于视觉识别（图生文）

---

## 一、Lyra Flash API（图像生成）

### 1.1 基础配置

| 配置项 | 值 |
|-------|-----|
| Base URL | `${IMAGE_API_BASE_URL}` |
| Model | `lyra-flash-9` |
| 认证方式 | Bearer Token |

### 1.2 文生图接口

**端点**
```
POST /images/generations
```

**请求头**
```json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer ${IMAGE_API_KEY}"
}
```

**请求体**
```json
{
  "model": "lyra-flash-9",
  "prompt": "中文图像描述",
  "size": "1792x1024",
  "response_format": "b64_json"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| model | string | 是 | 固定使用 `lyra-flash-9` |
| prompt | string | 是 | 中文图像生成提示词 |
| size | string | 否 | 图片尺寸，默认 `1792x1024` |
| response_format | string | 否 | 响应格式，推荐 `b64_json` |

**响应体**
```json
{
  "created": 1641234567,
  "data": [
    {
      "b64_json": "base64编码的图片数据"
    }
  ]
}
```

### 1.3 图生图接口

**端点**
```
POST /images/edits
```

**请求体**
```json
{
  "model": "lyra-flash-9",
  "prompt": "中文编辑指令",
  "image": "data:image/png;base64,{base64数据}",
  "size": "1792x1024",
  "response_format": "b64_json"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| model | string | 是 | 固定使用 `lyra-flash-9` |
| prompt | string | 是 | 中文图片编辑指令 |
| image | string | 是 | Base64 编码的参考图片（含 data URL 前缀） |
| size | string | 否 | 输出尺寸 |
| response_format | string | 否 | 响应格式 |

**响应体**
```json
{
  "data": [
    {
      "b64_json": "base64编码的生成图片"
    }
  ]
}
```

---

## 二、Qwen2.5-VL API（视觉识别）

### 2.1 基础配置

| 配置项 | 值 |
|-------|-----|
| Base URL | `${IMAGE_API_BASE_URL}` |
| Model | `qwen2.5-vl-72b-instruct` |
| 认证方式 | Bearer Token |

### 2.2 图生文接口

**端点**
```
POST /chat/completions
```

**请求头**
```json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer ${VISION_API_KEY}"
}
```

**请求体**
```json
{
  "model": "qwen2.5-vl-72b-instruct",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请描述这张图片"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,{base64数据}"
          }
        }
      ]
    }
  ],
  "max_tokens": 2000,
  "temperature": 0.7
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| model | string | 是 | 视觉模型名称 |
| messages | array | 是 | 消息列表，包含文本和图片 |
| max_tokens | int | 否 | 最大输出 token 数 |
| temperature | float | 否 | 温度参数（0-1） |

**响应体**
```json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1641234567,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是一张..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150
  }
}
```

---

## 三、错误码说明

| 状态码 | 说明 | 处理建议 |
|-------|------|---------|
| 400 | 请求参数错误 | 检查请求体格式和参数 |
| 401 | API 密钥无效 | 检查 API Key 是否正确 |
| 403 | 权限不足 | 检查 API Key 权限 |
| 429 | 请求频率限制 | 等待后重试 |
| 500 | 服务器内部错误 | 稍后重试 |
| 503 | 服务不可用 | 稍后重试 |

---

## 四、最佳实践

### 4.1 超时设置

- 文生图：建议 120-180 秒
- 图生图：建议 180-300 秒
- 图生文：建议 60-120 秒

### 4.2 重试策略

建议实现指数退避重试：
1. 首次重试：等待 1 秒
2. 第二次重试：等待 2 秒
3. 第三次重试：等待 4 秒

### 4.3 图片格式

- 支持格式：PNG、JPG、JPEG、WebP、GIF
- 推荐格式：PNG（无损）或 JPEG（有损但体积小）
- 最大文件大小：建议不超过 4MB

### 4.4 Base64 编码

图片必须使用完整的 Data URL 格式：
```
data:image/png;base64,iVBORw0KGgo...
```