通过个人 API Key 生成图片。推荐使用异步任务模式；同步响应继续兼容。模型参数以本页矩阵为准。
请求体设置 responseMode 为 async。接口很快返回 HTTP 202 和 taskId，不等待图片生成；之后用 GET 查询任务，直到拿到图片 URL。
curl -X POST 'https://prompthub.xin/api/openapi/v1/images/generations' \
-H 'Authorization: Bearer phk_你的API密钥' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "一只猫坐在窗边，清晨自然光",
"model": "platform-image-model-id",
"clientRequestId": "image_demo_001",
"responseMode": "async",
"parameters": {
"aspectRatio": "16:9",
"quality": "2k",
"count": 1
}
}'同一个 POST 接口，请求体设置 responseMode 为 sync（或省略）。请求会一直等待，生成完成后才返回 HTTP 200 和图片 URL；耗时过长时可能遇到客户端超时。
curl -X POST 'https://prompthub.xin/api/openapi/v1/images/generations' \
-H 'Authorization: Bearer phk_你的API密钥' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "一只猫坐在窗边，清晨自然光",
"model": "platform-image-model-id",
"clientRequestId": "image_demo_sync_001",
"responseMode": "sync",
"parameters": {
"aspectRatio": "16:9",
"quality": "2k",
"count": 1
}
}'素材
生成接口只接收 JSON 中的 URL，不接收文件本体、Base64 或 multipart。
PromptHub OSS URL 或供应商可访问的公网 URL 可直接放入素材数组。
referenceImages[].url = https://...先获取上传签名并直传 PromptHub OSS，再把响应中的 publicUrl 或 standardUrl 放入素材数组。
POST /openapi/v1/images/uploads/signature签名接口只接收 contentType；响应中的 host、policy、signature、accessKeyId、key 用于 OSS 表单直传。图片上限 20 MB；视频/音频还受模型和接口的时长限制。
curl -X POST 'https://prompthub.xin/api/openapi/v1/images/uploads/signature' \
-H 'Authorization: Bearer phk_你的API密钥' \
-H 'Content-Type: application/json' \
-d '{"contentType":"image/jpeg"}'
# 使用响应 data.host、data.policy、data.signature、data.accessKeyId、data.key 直传 OSS
curl -X POST '<data.host>' \
-F "key=<data.key>" \
-F "policy=<data.policy>" \
-F "OSSAccessKeyId=<data.accessKeyId>" \
-F "Signature=<data.signature>" \
-F "Content-Type=image/jpeg" \
-F "file=@./reference.jpg"01
除 parameters 外，所有字段都位于请求 JSON 顶层。
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| prompt | 是 | string | 图片描述和生成指令。 |
| model | 否 | string | 平台模型 ID；不传时使用默认图片模型。 |
| clientRequestId | 是 | string | 用户侧幂等 ID；重复提交不会重复扣点。 |
| responseMode | 否 | enum | 可选：async 立即返回任务（推荐）；sync 等待生成完成。省略时默认为 sync，以兼容已有调用。 |
| parameters | 否 | object | aspectRatio、quality、count 等模型参数。 |
| referenceImages | 否 | array | 参考图数组；仅支持 referenceImages=true 的模型。 |
02
数据实时来自平台模型目录，只展示可调用的平台模型 ID 和公开能力。
| 平台模型 | 平台模型 ID | 状态 | aspectRatio | quality | count | 参考图 |
|---|---|---|---|---|---|---|
| 正在读取平台模型目录... | ||||||
参考图使用 referenceImages 数组。是否支持及数量限制以平台模型表的公开能力为准。
@图片1 → referenceImages[0]
@图片2 → referenceImages[1]
标记只保留在 prompt 文本中，服务端按数组顺序传图，不会转换成供应商私有字段。
{
"prompt": "人物脸型参考@图片1，服装参考@图片2，产品参考@图片3",
"referenceImages": [
{ "url": "https://example.com/face.jpg", "mimeType": "image/jpeg" },
{ "url": "https://example.com/outfit.jpg", "mimeType": "image/jpeg" },
{ "url": "https://example.com/product.jpg", "mimeType": "image/jpeg" }
]
}03
responseMode=async 时立即返回 HTTP 202。保存 taskId，并按下方示例查询；重复请求返回已存在任务。
HTTP/1.1 202 Accepted
{
"success": true,
"data": {
"taskId": "task_image_123",
"object": "image_generation_task",
"status": "pending",
"model": "platform-image-model-id",
"prompt": "一只猫坐在窗边，清晨自然光",
"images": [],
"error": null
}
}04
同步模式不会返回 taskId。POST 请求等待生成完成后直接返回 HTTP 200，图片 URL 位于 data.images。
HTTP/1.1 200 OK
{
"success": true,
"data": {
"object": "image_generation",
"status": "completed",
"model": "platform-image-model-id",
"images": [
{ "url": "https://media.prompthub.xin/...png" }
]
}
}05
将创建响应中的 taskId 替换到路径中，直到 status 为 completed 或 failed。
curl 'https://prompthub.xin/api/openapi/v1/images/generations/{taskId}' \
-H 'Authorization: Bearer phk_你的API密钥'
{
"success": true,
"data": {
"taskId": "task_image_123",
"object": "image_generation_task",
"status": "completed",
"model": "platform-image-model-id",
"images": [
{ "url": "https://media.prompthub.xin/...png" }
],
"finishedAt": "2026-09-22T08:30:00.000Z"
}
}