API 参考文档
前置条件
在开始使用 ImgMCP API 之前，请确保您已准备好以下内容：
- ImgMCP 账户： 您需要在平台上注册账户。如果您还没有账户，请前往 管理平台 完成注册。
- API 密钥： 需要 API 密钥来验证您的请求。注册并登录后，您可以在管理控制台的 API 密钥 页面找到您的默认 API 密钥。
请确保您的 API 密钥安全保密。
核心配置
- API 基础 URL：
https://api.imgmcp.com- 身份验证方法： ImgMCP 使用 API 密钥进行身份验证。您需要在 HTTP 请求的
Authorization头中提供密钥，格式如下：
Authorization: Bearer <您的 API 密钥>API 端点
创作
POST /v1/imagine
创建新的多媒体生成任务，包括图像、音频、视频和其他内容类型。
请求参数：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| n | integer | 否 | 要生成的任务数量（1-8，默认值：1） |
| model | string | 否 | 用于生成的模型名称（如未指定则自动选择） |
| style | string | 否 | 要应用的风格名称 |
| prompt | string | 否 | 描述所需内容的文本提示（某些模型无需提示即可工作） |
| reference | string[] | 否 | 参考资料 URL 数组（图像、音频、视频等） |
注意：不同模型可能接受特定于其功能的其他参数，并且对上述参数可能有不同的要求。
请求示例：
curl -X POST https://api.imgmcp.com/v1/imagine \
-H "Authorization: Bearer <您的 API 密钥>" \
-H "Content-Type: application/json" \
-d '{
"n": 2,
"model": "gpt-image-1",
"style": "",
"prompt": "山峰上美丽的日落",
"reference": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]
}'响应示例：
{
"ids": ["task-uuid-1", "task-uuid-2"]
}重新创作
POST /v1/reimagine
对现有多媒体生成结果执行操作，创建新的变体或增强效果。
请求参数：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| taskID | string | 是 | 来自原始 imagine 请求的任务 ID |
| index | integer | 是 | 资源索引（从 1 开始） |
| action | string | 是 | 要执行的操作：upscale、variation 或 reroll |
| prompt | string | 否 | 操作的附加提示 |
| reference | string[] | 否 | 参考资料 URL 数组 |
操作类型：
upscale：增强所选多媒体内容的分辨率或质量variation：生成所选多媒体内容的变体reroll：使用新结果重新生成整个任务
请求示例：
curl -X POST https://api.imgmcp.com/v1/reimagine \
-H "Authorization: Bearer <您的 API 密钥>" \
-H "Content-Type: application/json" \
-d '{
"taskID": "task-uuid-2",
"index": 1,
"action": "upscale"
}'响应示例：
{
"ids": ["task-uuid-3"]
}任务查询
GET /v1/tasks
检索用户任务的分页列表，支持可选过滤。
查询参数：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| model | string | 否 | 按模型名称过滤 |
| status | integer | 否 | 按任务状态过滤 |
| start | string | 否 | 开始日期过滤（YYYY-MM-DD） |
| end | string | 否 | 结束日期过滤（YYYY-MM-DD） |
| page | integer | 否 | 页码（默认值：1） |
| pageSize | integer | 否 | 每页项目数（默认值：20） |
任务状态值：
0：待处理1：处理中2：已完成3：失败
请求示例：
curl -X GET "https://api.imgmcp.com/v1/tasks?page=1&pageSize=10" \
-H "Authorization: Bearer <您的 API 密钥>"响应示例：
{
"total": 1,
"page": 1,
"pageSize": 100,
"tasks": [
{
"id": "task-uuid-1",
"model": "gpt-image-1",
"style": "",
"cost": 10,
"request": {
"n": 1,
"model": "gpt-image-1",
"prompt": "山峰上美丽的日落",
"reference": [
"https://example.com/ref1.jpg",
"https://example.com/ref2.jpg"
]
},
"response": {
"assets": [
"asset-uuid-1",
"asset-uuid-2",
"asset-uuid-3",
"asset-uuid-4"
]
},
"status": 2,
"startedAt": "2025-06-11T15:18:42Z",
"finishedAt": "2025-06-11T15:20:37Z",
"createdAt": "2025-06-11T15:18:42Z",
"updatedAt": "2025-06-11T15:20:37Z"
}
]
}错误处理
所有端点返回一致的错误响应：
{
"message": "描述出错原因的错误消息"
}常见 HTTP 状态码：
400：错误请求 - 无效参数401：未授权 - 无效或缺失 API 密钥403：禁止访问 - 权限不足429：请求过多 - 超出速率限制500：内部服务器错误 - 服务器端错误
下一步：
您已成功配置 ImgMCP API 访问。现在可以开始探索平台提供的各种图像生成和管理功能。请参考后续章节获取更详细的使用示例。