pixel/docs/API.md

Pixel API 文档

概述

本文档描述了 Pixel 后端 API 的核心端点，重点介绍模型配置和生成 API。

基础 URL: http://localhost:8000/api/v1

认证: 目前不需要认证（开发环境）

---

模型 ID 格式

所有 API 使用复合 ID 格式来标识模型：

provider/model_key

示例：

• dashscope/qwen-image - DashScope 的 Qwen 图片生成模型
• dashscope/wan2.6-video - DashScope 的 Wan 2.6 视频生成模型
• volcengine/doubao-tts - 火山引擎的豆包 TTS 模型
• modelscope/qwen-image - ModelScope 的 Qwen 图片生成模型

格式规则：

• 必须包含一个 / 分隔符
• provider 和 model_key 都不能为空
• 不支持多个 / 分隔符

---

模型配置 API

获取所有模型配置

获取系统中所有可用的模型配置，按类型分组。

端点: GET /api/v1/models

响应格式:

{
  "code": "200",
  "message": "success",
  "data": {
    "image": {
      "dashscope/qwen-image": {
        "id": "dashscope/qwen-image",
        "name": "Qwen Image",
        "type": "image",
        "provider": "dashscope",
        "model_key": "qwen-image",
        "is_default": true,
        "enabled": true,
        "capabilities": {
          "supportsLora": true,
          "supportsRefImage": true
        },
        "resolutions": {
          "1K": {
            "16:9": "1280*720",
            "1:1": "1024*1024"
          },
          "2K": {
            "16:9": "2560*1440",
            "1:1": "2048*2048"
          }
        }
      },
      "modelscope/qwen-image": {
        "id": "modelscope/qwen-image",
        "name": "ModelScope Qwen Image",
        "type": "image",
        "provider": "modelscope",
        "model_key": "qwen-image",
        "is_default": false,
        "enabled": true,
        "capabilities": {
          "supportsLora": true
        }
      }
    },
    "video": {
      "dashscope/wan2.6-video": {
        "id": "dashscope/wan2.6-video",
        "name": "Wan 2.6 Video",
        "type": "video",
        "provider": "dashscope",
        "model_key": "wan2.6-video",
        "is_default": true,
        "enabled": true,
        "durations": {
          "5s": "5秒",
          "10s": "10秒"
        }
      }
    },
    "audio": {
      "volcengine/doubao-tts": {
        "id": "volcengine/doubao-tts",
        "name": "豆包 TTS",
        "type": "audio",
        "provider": "volcengine",
        "model_key": "doubao-tts",
        "is_default": true,
        "enabled": true,
        "voices": [
          {
            "id": "zh_female_qingxin",
            "name": "清新女声",
            "language": "zh"
          }
        ]
      }
    },
    "llm": {
      "dashscope/qwen-plus": {
        "id": "dashscope/qwen-plus",
        "name": "Qwen Plus",
        "type": "llm",
        "provider": "dashscope",
        "model_key": "qwen-plus",
        "is_default": true,
        "enabled": true
      }
    }
  }
}

字段说明：

字段	类型	说明
id	string	复合 ID，格式为 provider/model_key
name	string	模型显示名称
type	string	模型类型：image、video、audio、llm
provider	string	提供商名称
model_key	string	模型键名
is_default	boolean	是否为该类型的默认模型
enabled	boolean	是否启用
capabilities	object	模型能力（可选）
resolutions	object	支持的分辨率（图片模型）
durations	object	支持的时长（视频模型）
voices	array	支持的音色（音频模型）

---

图片生成 API

生成图片

创建图片生成任务。

端点: POST /api/v1/generations/image

请求体:

{
  "prompt": "a beautiful sunset over mountains",
  "model": "dashscope/qwen-image",
  "negativePrompt": "blurry, low quality",
  "resolution": "2K",
  "aspectRatio": "16:9",
  "n": 1,
  "imageInputs": ["https://example.com/ref-image.jpg"],
  "extraParams": {
    "loras": [
      {
        "model": "dashscope/anime-style",
        "weight": 0.8
      }
    ]
  },
  "projectId": "proj_123",
  "source": "canvas",
  "sourceId": "canvas_456"
}

参数说明：

参数	类型	必填	说明
prompt	string	✅	生成提示词
model	string	✅	模型复合 ID，格式：provider/model_key
negativePrompt	string	❌	负面提示词
resolution	string	❌	分辨率级别（如 1K、2K），默认 1K
aspectRatio	string	❌	宽高比（如 16:9、1:1）
n	integer	❌	生成数量，默认 1
imageInputs	array	❌	参考图片 URL 列表
extraParams	object	❌	额外参数（如 LoRA 配置）
projectId	string	❌	项目 ID
source	string	❌	来源标识
sourceId	string	❌	来源对象 ID

响应:

{
  "code": "200",
  "message": "success",
  "data": {
    "task_id": "task_abc123"
  }
}

错误响应:

{
  "code": "400",
  "message": "Model must be in format 'provider/model_key', got: 'qwen-image'. Example: 'dashscope/qwen-image'"
}

{
  "code": "404",
  "message": "Model 'invalid/model' not found. Available models can be fetched from /api/v1/models"
}

---

视频生成 API

生成视频

创建视频生成任务。

端点: POST /api/v1/generations/video

请求体:

{
  "prompt": "a cat playing with a ball",
  "model": "dashscope/wan2.6-video",
  "negativePrompt": "static, blurry",
  "duration": "5s",
  "resolution": "720p",
  "n": 1,
  "imageInputs": ["https://example.com/first-frame.jpg"],
  "projectId": "proj_123"
}

参数说明：

参数	类型	必填	说明
prompt	string	✅	生成提示词
model	string	✅	模型复合 ID，格式：provider/model_key
negativePrompt	string	❌	负面提示词
duration	string	❌	视频时长（如 5s、10s）
resolution	string	❌	分辨率（如 720p、1080p）
n	integer	❌	生成数量，默认 1
imageInputs	array	❌	参考图片 URL 列表（首帧）
projectId	string	❌	项目 ID

响应:

{
  "code": "200",
  "message": "success",
  "data": {
    "task_id": "task_xyz789"
  }
}

---

音频生成 API

生成音频

创建音频生成任务（TTS）。

端点: POST /api/v1/generations/audio

请求体:

{
  "prompt": "Hello, welcome to Pixel AI!",
  "model": "volcengine/doubao-tts",
  "voice": "zh_female_qingxin",
  "speed": 1.0,
  "projectId": "proj_123"
}

参数说明：

参数	类型	必填	说明
prompt	string	✅	要转换的文本
model	string	✅	模型复合 ID，格式：provider/model_key
voice	string	❌	音色 ID
speed	float	❌	语速，默认 1.0
projectId	string	❌	项目 ID

响应:

{
  "code": "200",
  "message": "success",
  "data": {
    "task_id": "task_audio123"
  }
}

---

任务查询 API

获取任务状态

查询生成任务的状态和结果。

端点: GET /api/v1/tasks/{task_id}

响应:

{
  "code": "200",
  "message": "success",
  "data": {
    "id": "task_abc123",
    "type": "image",
    "status": "completed",
    "model": "dashscope/qwen-image",
    "params": {
      "prompt": "a beautiful sunset over mountains",
      "resolution": "2K",
      "aspectRatio": "16:9"
    },
    "result": {
      "images": [
        {
          "url": "https://example.com/generated-image.jpg",
          "width": 2560,
          "height": 1440
        }
      ]
    },
    "created_at": "2026-02-11T10:00:00Z",
    "updated_at": "2026-02-11T10:00:30Z"
  }
}

任务状态：

• pending - 等待处理
• processing - 处理中
• completed - 已完成
• failed - 失败

---

错误处理

错误响应格式

所有错误响应遵循统一格式：

{
  "code": "400",
  "message": "详细的错误描述",
  "request_id": "req_123456"
}

常见错误码

错误码	说明
400	请求参数错误（如模型 ID 格式不正确）
404	资源不存在（如模型不存在）
500	服务器内部错误
503	服务暂时不可用

模型 ID 格式错误

错误请求:

{
  "prompt": "a cat",
  "model": "qwen-image"
}

错误响应:

{
  "code": "400",
  "message": "Model must be in format 'provider/model_key', got: 'qwen-image'. Example: 'dashscope/qwen-image'"
}

模型不存在

错误请求:

{
  "prompt": "a cat",
  "model": "invalid/model"
}

错误响应:

{
  "code": "404",
  "message": "Model 'invalid/model' not found. Available models can be fetched from /api/v1/models"
}

---

最佳实践

1. 使用复合 ID

始终使用完整的复合 ID 格式：

✅ 正确:

{
  "model": "dashscope/qwen-image"
}

❌ 错误:

{
  "model": "qwen-image"
}

2. 获取可用模型

在调用生成 API 之前，先获取可用模型列表：

// 1. 获取模型配置
const response = await fetch('/api/v1/models');
const { data } = await response.json();

// 2. 使用模型 ID
const imageModels = data.image;
const modelId = Object.keys(imageModels)[0]; // "dashscope/qwen-image"

// 3. 调用生成 API
await fetch('/api/v1/generations/image', {
  method: 'POST',
  body: JSON.stringify({
    prompt: "a cat",
    model: modelId
  })
});

3. 错误处理

始终处理可能的错误：

try {
  const response = await fetch('/api/v1/generations/image', {
    method: 'POST',
    body: JSON.stringify({
      prompt: "a cat",
      model: "dashscope/qwen-image"
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.message);
    return;
  }
  
  const { data } = await response.json();
  console.log('Task ID:', data.task_id);
} catch (error) {
  console.error('Network Error:', error);
}

4. 轮询任务状态

生成任务是异步的，需要轮询状态：

async function waitForTask(taskId) {
  while (true) {
    const response = await fetch(`/api/v1/tasks/${taskId}`);
    const { data } = await response.json();
    
    if (data.status === 'completed') {
      return data.result;
    }
    
    if (data.status === 'failed') {
      throw new Error('Task failed');
    }
    
    // 等待 2 秒后重试
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

---

迁移指南

从旧格式迁移

如果你的代码使用了旧的 provider 参数，需要进行以下修改：

旧代码:

await fetch('/api/v1/generations/image', {
  method: 'POST',
  body: JSON.stringify({
    prompt: "a cat",
    model: "qwen-image",
    provider: "dashscope"  // ❌ 不再支持
  })
});

新代码:

await fetch('/api/v1/generations/image', {
  method: 'POST',
  body: JSON.stringify({
    prompt: "a cat",
    model: "dashscope/qwen-image"  // ✅ 使用复合 ID
  })
});

前端辅助函数

如果你的前端代码有 getProviderForModel 函数，可以直接删除：

旧代码:

const provider = getProviderForModel(model, 'image');  // ❌ 删除
await ImageGenerationService.generate({
  model,
  provider,  // ❌ 删除
  prompt
});

新代码:

await ImageGenerationService.generate({
  model,  // ✅ 直接使用复合 ID
  prompt
});

---

交互式文档

访问 FastAPI 自动生成的交互式文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

---

更新日志

v2.0.0 (2026-02-11)

• ✅ 统一使用复合 ID 格式（provider/model_key）
• ✅ 移除冗余的 provider 参数
• ✅ 模型配置 API 返回按类型分组的 HashMap
• ✅ 改进错误消息，提供清晰的格式说明
• ✅ 简化前端 API 调用

---

支持

如有问题，请联系开发团队或查看：

• GitHub Issues
• 开发文档