docs/v1.0/server/guides/ai-api-testing.md

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. 输入请求体：

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

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

使用 curl

# 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. 输入请求参数：

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

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

方法 B: 使用 curl

# 设置 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"
  }'

预期响应

{
  "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

# 查询任务状态（替换为实际的 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"

预期响应

{
  "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

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

预期响应

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

---

📊 完整测试脚本

#!/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，然后执行：

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

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

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

2. 402 Payment Required

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

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

3. 403 Forbidden

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

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

4. 404 Not Found

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

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

5. 422 Validation Error

{
  "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 设计规范
• AI 服务文档
• 自动化测试用例
• 测试规范

---

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