API 规范
生成图片
生成或编辑图片。
POST
bearerheader
AuthorizationBearer <token>- body
prompt*string必填。图片生成或编辑的指令描述。
size?string可选。输出尺寸，格式为 `宽x高`。总像素需在 512×512 到 2048×2048 之间。文生图默认 `2048x2048`，编辑模式默认取最后一张输入图的尺寸。
images?array<>可选。编辑模式下的参考图片，通过 multipart 上传。最多 3 张，支持 PNG、JPEG 或 WebP，单张不超过 10 MiB。文生图时省略。
Items
items <= 3application/json- response
created?number请求创建时间，Unix 时间戳（秒）。
data?array<>Items
1 <= items <= 1consumed?number本次请求消耗的 credits（固定 0.5）。
error?string错误码，当请求无法提交时返回。该字段会随 HTTP 201 一起在响应体中返回，因此客户端必须检查此字段，而不能仅依赖 HTTP 状态码。成功时省略此字段。错误码详细请参考 [errors](/zh/api-specification/errors)。
Value in
"NO_SUCH_TASK""ASSET_NOT_AVAILABLE""IMAGE_LABEL_LENGTH_TOO_LONG""INVALID_REQUEST""API_NO_ACTIVE_SUBSCRIPTION""API_SUBSCRIPTION_PLAN_TOO_LOW""API_PARALLELISM_LIMIT_REACHED""API_INSUFFICIENT_FUNDS""API_OBJECT_NOT_FOUND_ON_IMAGE""IMAGE_CONTENT_VIOLATION""PERMISSION_DENIED""API_UNKNOWN"message?string成功消息或详细错误信息。
Example Request
curl -X POST 'https://api.hyper3d.com/api/v2/images' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "string"}'Example Response
{ "created": 0, "data": [ { "b64_json": "string", "revised_prompt": "string" } ], "consumed": 0, "error": "NO_SUCH_TASK", "message": "string"}/api/v2/images 会立即返回一张 base64 编码的图片（HTTP 201），每次调用消耗 0.5 Credits — 无需轮询状态，也无需下载步骤。
同一接口支持两种输入方式：
| 模式 | Content-Type | 适用场景 |
|---|---|---|
| 文生图 | application/json | 仅根据 prompt 生成图片 |
| 图生图 / 编辑 | multipart/form-data | 基于一张或多张参考图进行编辑 |
输入参数
prompt（必填）：图片生成或编辑的指令描述。size（可选）：输出尺寸，格式为宽x高。总像素需在 512×512 到 2048×2048 之间。文生图默认2048x2048，编辑模式默认取最后一张输入图的尺寸。images（可选，仅 multipart 模式）：最多 3 张参考图片，单张不超过 10 MiB。支持 PNG、JPEG、WebP。文生图时省略。
文生图示例
将 prompt 和 size 以 JSON 格式发送，无需上传文件。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/images' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
"prompt": "A majestic snowy owl perched on a frost-covered branch, soft golden hour lighting, hyper-detailed feathers",
"size": "1024x1024"
}'
图生图示例
将参考图作为 multipart 文件与 prompt 一起上传。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/images' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'prompt=Add a glowing crescent moon behind the castle, atmospheric fog' \
--form 'size=1024x1024' \
--form 'images=@./castle.png'
响应
成功响应会立即返回，包含不带 data URL 前缀的 base64 图片字节 — 请解码 data[0].b64_json 得到原始 PNG/JPEG/WebP 内容。
{
"created": 1728547200,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
"revised_prompt": "A majestic snowy owl perched on a frost-covered branch, soft golden hour lighting, hyper-detailed feathers, photorealistic, 4k"
}
],
"consumed": 0.5
}
| 字段 | 说明 |
|---|---|
created | 请求创建时间，Unix 时间戳（秒） |
data[0].b64_json | Base64 编码的图片字节 — 解码后可保存为文件 |
data[0].revised_prompt | 模型改写后的实际生成 prompt（可能缺失） |
consumed | 本次请求消耗的 Credits（固定 0.5） |
error | 请求失败时的应用错误码（成功时缺失） |
message | 人类可读的错误描述（成功时缺失） |