# AI API 手动测试指南

> **文档版本**：v1.0  
> **最后更新**：2026-01-30  
> **适用场景**：手动测试 AI API 功能，补充自动化测试

---

## 📋 接口信息

**接口地址**: `POST /api/v1/ai/generate-image`

**功能**: 创建图片生成任务

**认证**: 需要 Bearer Token

---

## 🌐 Swagger 文档访问

**本地访问**: http://localhost:6170/docs

**容器内访问**: http://0.0.0.0:6170/docs

---

## 🔑 步骤 1: 获取认证 Token

### 使用 Swagger UI

1. 打开 http://localhost:6170/docs
2. 找到 `POST /api/v1/auth/login/phone` 接口
3. 点击 "Try it out"
4. 输入请求体：

```json
{
  "phone": "+8613800138000",
  "verification_code": "123456",
  "country_code": "+86"
}
```

5. 点击 "Execute"
6. 从响应中复制 `access_token`

### 使用 curl

```bash
# 1. 登录获取 token
curl -X POST "http://localhost:6170/api/v1/auth/login/phone" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+8613800138000",
    "verification_code": "123456",
    "country_code": "+86"
  }'

# 响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "user": {
      "user_id": "019c0d66-9c58-7510-aff7-ae5af99a560d",
      "username": "testuser",
      "nickname": "测试用户"
    }
  }
}
```

---

## 🎨 步骤 2: 测试图片生成接口

### 方法 A: 使用 Swagger UI（推荐）

1. 在 Swagger 页面顶部点击 **"Authorize"** 按钮
2. 输入 Token（格式：`Bearer <your_token>`）
3. 点击 "Authorize" 确认
4. 找到 `POST /api/v1/ai/generate-image` 接口
5. 点击 "Try it out"
6. 输入请求参数：

```json
{
  "prompt": "一只可爱的猫咪",
  "width": 1024,
  "height": 1024,
  "style": "realistic"
}
```

7. 点击 "Execute"
8. 查看响应结果

### 方法 B: 使用 curl

```bash
# 设置 Token 变量（替换为你的实际 token）
export TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# 创建图片生成任务
curl -X POST "http://localhost:6170/api/v1/ai/generate-image" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的猫咪",
    "width": 1024,
    "height": 1024,
    "style": "realistic"
  }'
```

### 预期响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "job_id": "019c0d66-9cac-7232-98fd-fa6eeabd498d",
    "task_id": "abc123-def456",
    "status": "pending",
    "estimated_cost": 0.05,
    "estimated_credits": 10
  },
  "timestamp": "2026-01-30T05:35:54.123456+00:00"
}
```

---

## 🔍 步骤 3: 查询任务状态

### 使用 Swagger UI

1. 找到 `GET /api/v1/ai/jobs/{job_id}` 接口
2. 点击 "Try it out"
3. 输入上一步返回的 `job_id`
4. 点击 "Execute"

### 使用 curl

```bash
# 查询任务状态（替换为实际的 job_id）
JOB_ID="019c0d66-9cac-7232-98fd-fa6eeabd498d"

curl -X GET "http://localhost:6170/api/v1/ai/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN"
```

### 预期响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "job_id": "019c0d66-9cac-7232-98fd-fa6eeabd498d",
    "job_type": 2,
    "status": 1,
    "progress": 0,
    "input_data": {
      "prompt": "一只可爱的猫咪",
      "width": 1024,
      "height": 1024,
      "style": "realistic"
    },
    "output_data": null,
    "error_message": null,
    "model_name": "stable-diffusion-xl",
    "cost": 0.05,
    "credits_used": 10,
    "created_at": "2026-01-30T05:35:54.123456+00:00",
    "updated_at": "2026-01-30T05:35:54.123456+00:00"
  }
}
```

---

## ❌ 步骤 4: 取消任务

### 使用 Swagger UI

1. 找到 `POST /api/v1/ai/jobs/{job_id}/cancel` 接口
2. 点击 "Try it out"
3. 输入 `job_id`
4. 点击 "Execute"

### 使用 curl

```bash
# 取消任务
curl -X POST "http://localhost:6170/api/v1/ai/jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $TOKEN"
```

### 预期响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "任务已取消"
  }
}
```

---

## 📊 完整测试脚本

```bash
#!/bin/bash

# 配置
API_BASE="http://localhost:6170"
PHONE="+8613800138000"
CODE="123456"

echo "=== AI 图片生成 API 测试 ==="
echo ""

# 1. 登录获取 token
echo "1️⃣  登录获取 Token..."
LOGIN_RESPONSE=$(curl -s -X POST "$API_BASE/api/v1/auth/login/phone" \
  -H "Content-Type: application/json" \
  -d "{
    \"phone\": \"$PHONE\",
    \"verification_code\": \"$CODE\",
    \"country_code\": \"+86\"
  }")

TOKEN=$(echo $LOGIN_RESPONSE | jq -r '.data.access_token')
echo "✅ Token: ${TOKEN:0:50}..."
echo ""

# 2. 创建图片生成任务
echo "2️⃣  创建图片生成任务..."
CREATE_RESPONSE=$(curl -s -X POST "$API_BASE/api/v1/ai/generate-image" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的猫咪",
    "width": 1024,
    "height": 1024,
    "style": "realistic"
  }')

JOB_ID=$(echo $CREATE_RESPONSE | jq -r '.data.job_id')
echo "✅ Job ID: $JOB_ID"
echo "📊 响应: $(echo $CREATE_RESPONSE | jq -c '.data')"
echo ""

# 3. 查询任务状态
echo "3️⃣  查询任务状态..."
STATUS_RESPONSE=$(curl -s -X GET "$API_BASE/api/v1/ai/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN")

echo "✅ 状态: $(echo $STATUS_RESPONSE | jq -r '.data.status')"
echo "📊 响应: $(echo $STATUS_RESPONSE | jq -c '.data')"
echo ""

# 4. 取消任务
echo "4️⃣  取消任务..."
CANCEL_RESPONSE=$(curl -s -X POST "$API_BASE/api/v1/ai/jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $TOKEN")

echo "✅ 取消结果: $(echo $CANCEL_RESPONSE | jq -r '.data.message')"
echo ""

# 5. 验证任务已取消
echo "5️⃣  验证任务已取消..."
VERIFY_RESPONSE=$(curl -s -X GET "$API_BASE/api/v1/ai/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN")

echo "✅ 最终状态: $(echo $VERIFY_RESPONSE | jq -r '.data.status')"
echo ""

echo "=== 测试完成 ==="
```

保存为 `test_ai_api.sh`，然后执行：

```bash
chmod +x test_ai_api.sh
./test_ai_api.sh
```

---

## 📝 请求参数说明

### GenerateImageRequest

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `prompt` | string | ✅ | - | 提示词 |
| `model` | string | ❌ | null | 模型名称（不填则使用默认模型） |
| `width` | integer | ❌ | 1024 | 图片宽度 |
| `height` | integer | ❌ | 1024 | 图片高度 |
| `style` | string | ❌ | null | 风格（如 realistic, anime, cartoon） |
| `project_id` | string | ❌ | null | 关联项目 ID |
| `storyboard_id` | string | ❌ | null | 关联分镜 ID |

---

## ⚠️ 常见错误

### 1. 401 Unauthorized

```json
{
  "detail": "未授权访问"
}
```

**原因**: Token 无效或已过期  
**解决**: 重新登录获取新 Token

### 2. 402 Payment Required

```json
{
  "detail": "积分不足"
}
```

**原因**: 用户积分余额不足  
**解决**: 充值积分

### 3. 403 Forbidden

```json
{
  "detail": "没有权限访问该任务"
}
```

**原因**: 尝试访问其他用户的任务  
**解决**: 只能访问自己创建的任务

### 4. 404 Not Found

```json
{
  "detail": "任务不存在"
}
```

**原因**: Job ID 不存在  
**解决**: 检查 Job ID 是否正确

### 5. 422 Validation Error

```json
{
  "detail": [
    {
      "loc": ["body", "prompt"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

**原因**: 缺少必填参数  
**解决**: 检查请求参数是否完整

---

## 🎯 测试检查清单

- [ ] 能否成功登录获取 Token
- [ ] 能否创建图片生成任务
- [ ] 返回的 job_id 格式是否正确（UUID v7）
- [ ] 能否查询任务状态
- [ ] 任务状态是否为 PENDING 或 PROCESSING
- [ ] 能否取消任务
- [ ] 取消后状态是否变为 CANCELLED
- [ ] 积分是否正确扣除和退还
- [ ] 无 Token 访问是否返回 401/403
- [ ] 无效 job_id 是否返回 404

---

## 📚 相关文档

- [API 设计规范](../../requirements/api-design-specification.md)
- [AI 服务文档](../../requirements/backend/04-services/ai/ai-service.md)
- [自动化测试用例](../../../server/tests/integration/test_ai_api_workflow.py)
- [测试规范](../../../.claude/skills/jointo-tech-stack/references/testing.md)

---

**文档版本**：v1.0  
**最后更新**：2026-01-30