OpenAPI

Async recommended · Sync supported

Image API Documentation

Generate images with your personal API Key. Asynchronous tasks are recommended, with synchronous responses retained for compatibility. Supported parameters are listed below.

Manage API Key

Async submission (recommended)

Set responseMode to async in the request body. The API quickly returns HTTP 202 and a taskId without waiting for the image; then poll the task with GET until the image URL is ready.

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
    }
  }'

Synchronous submission (compatibility)

Use the same POST endpoint and set responseMode to sync (or omit it). The request stays open until generation finishes, then returns HTTP 200 and the image URL; long jobs may hit client timeouts.

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
    }
  }'

素材

How to provide assets

Generation endpoints accept URLs in JSON only; they do not accept file bodies, Base64, or multipart uploads.

Existing public URL

Use a PromptHub OSS URL or another URL reachable by the backend and model directly in the asset array.

referenceImages[].url = https://...

Local file

Get an upload signature, upload directly to PromptHub OSS, then put publicUrl or standardUrl from the response in the asset array.

POST /openapi/v1/images/uploads/signature

The signature endpoint only receives contentType. Use host, policy, signature, accessKeyId, and key from its response for the OSS form upload. Images are limited to 20 MB; video/audio also have duration and model limits.

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"

Request fields

All fields are top-level JSON properties except parameters.

Field	Required	Type	Description
prompt	Yes	string	Image description and generation instructions.
model	No	string	Platform model ID; the default image model is used when omitted.
clientRequestId	Yes	string	Client idempotency ID; retries do not charge twice.
responseMode	No	enum	Optional: async returns a task immediately (recommended); sync waits for generation. Defaults to sync to preserve existing integrations.
parameters	No	object	Model parameters such as aspectRatio, quality, and count.
referenceImages	No	array	Reference image array; only supported when referenceImages=true.

Image models and allowed values

Data is loaded from the platform model catalog and includes only callable platform model IDs and public capabilities.

Platform model	Platform model ID	Status	aspectRatio	quality	count	References
Loading the platform model catalog...

Common parameters

aspectRatio: Use the ratios listed for each model; unsupported ratios return INVALID_REQUEST.
quality: Use the values in the platform model table above
count: Use the values in the platform model table above

Reference image rules

Send reference images in referenceImages. Support and count limits come from the public capabilities in the platform model table.

@图片1 → referenceImages[0]

@图片2 → referenceImages[1]

The tags remain in the prompt text; the server sends images in array order and does not convert them into provider-specific fields.

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

Async submission response

With responseMode=async, the API immediately returns HTTP 202. Store taskId and query it as shown below; retries return the existing task.

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
  }
}

Synchronous response

Synchronous mode does not return a taskId. The POST request waits for generation and returns HTTP 200 with image URLs in 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" }
    ]
  }
}

Query a task

Replace taskId in the path and poll until status is completed or 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"
  }
}

Need to create or regenerate an API Key? Open account settings

Async submission (recommended)

Set responseMode to async in the request body. The API quickly returns HTTP 202 and a taskId without waiting for the image; then poll the task with GET until the image URL is ready.

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
    }
  }'

Synchronous submission (compatibility)

Use the same POST endpoint and set responseMode to sync (or omit it). The request stays open until generation finishes, then returns HTTP 200 and the image URL; long jobs may hit client timeouts.

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
    }
  }'

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"

Field

Required

Type

Description

prompt

Yes

string

Image description and generation instructions.

model

string

Platform model ID; the default image model is used when omitted.

clientRequestId

Yes

string

Client idempotency ID; retries do not charge twice.

responseMode

enum

Optional: async returns a task immediately (recommended); sync waits for generation. Defaults to sync to preserve existing integrations.

parameters

object

Model parameters such as aspectRatio, quality, and count.

referenceImages

array

Reference image array; only supported when referenceImages=true.

Platform model

Platform model ID

Status

aspectRatio

quality

count

References

Loading the platform model catalog...

Reference image rules

Send reference images in referenceImages. Support and count limits come from the public capabilities in the platform model table.

@图片1 → referenceImages[0]

@图片2 → referenceImages[1]

The tags remain in the prompt text; the server sends images in array order and does not convert them into provider-specific fields.

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

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 } }

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" } ] } }

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