Topaz Image Upscale

图片增强与放大，最高 4 倍，细节清晰自然。

topaz/topaz-image-upscale/image-upscale

能力

最适合

•概念艺术与情绪板
•产品与营销视觉素材
•大规模批量生成

不适合

•小字号文字的精确渲染
•品牌标志的精确还原
•矢量输出

身份验证

API 密钥标头

Uika API 使用 API 密钥来验证请求。将您的密钥发送到 X-API 密钥标题。API 密钥必须保密，不要暴露在浏览器或其他客户端代码中。请从服务端调用 API。登录后的试玩使用控制台会话，不会发送你的 API 密钥。

标题

X-API-Key: YOUR_API_KEY

端点

异步·轮询结果

发布https://api.dev.pika.art/v1/media/topaz/topaz-image-upscale/image-upscale生成端点

获取https://api.dev.pika.art/v1/media/jobs/{request_id}民意调查直至完成

获取https://api.dev.pika.art/v1/media/jobs/{request_id}/content输出 URL，适用于仅保留 id 的客户端

删除https://api.dev.pika.art/v1/media/jobs/{request_id}删除存储的媒体并提示

参考上传

媒体输入

媒体输入接受任何公共 URL。要使用本地文件，请将其 content_type 和 size_bytes 发布到 /v1/media/uploads，将文件放入返回的 upload_url，然后传递 url.

上传

# 1. Request a presigned upload URL. Send the file's content
#    type and its exact size in bytes.
curl -X POST https://api.dev.pika.art/v1/media/uploads \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "image/png", "size_bytes": 12345}'

# The response returns two URLs:
#   upload_url: a temporary URL to upload the file to. Expires in 5 minutes.
#   url:        the permanent Uika URL. Pass it to the model as the input.
# {
#   "upload_url": "https://upload.r2.pika.art/...?X-Amz-Signature=...",
#   "url": "https://cdn.pika.art/v2/media/uploads/org_abc/9f8e7d.png"
# }

# 2. Upload the file to upload_url, then pass url to the model.
curl -X PUT "<upload_url>" \
  -H "Content-Type: image/png" \
  --data-binary @input.png

生成

POST /v1/media/topaz/topaz-image-upscale/image-upscale

请求

curl -X POST https://api.dev.pika.art/v1/media/topaz/topaz-image-upscale/image-upscale \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://cdn.pika.art/v2/files/agent/d45537b3-7c9d-4d7e-99c4-af52f07b1599/topaz-rabbits-input.png",
  "upscale_factor": "x2",
  "model": "standard-v2"
}'

返回数据

{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "queued"
}

请求正文

image_urlstringrequired

要升级的图像的 URL。

upscale_factorenum

将图像放大多少：原始尺寸的 2 倍、3 倍或 4 倍。

模型枚举

Topaz增强模型。标准系列（真实输入放大）：`standard-v2`（默认，通用）、`low-resolution-v2`（小/降级源）、`cgi`（艺术和 CGI）、`high-fidelity-v2`（细节保留）、`text-refine`（文本和形状）。生成系列（添加合成细节，价格更高）：`redefine`（提示驱动）、`standard-max`、`wonder`、`wonder-3`、`wonder-3.5`。

output_formatenum

输出图像格式；省略保留提供程序默认值 (jpeg)。

crop_to_fillboolean

当输出纵横比不同时，裁剪以填充输出尺寸而不是默认的信箱。

subject_detectionenum

应用增强功能的地方；省略让 Topaz 自动配置。

face_enhancementboolean

应用Topaz的人脸恢复模型。如果为 true，则需要 `face_enhancement_strength` 和 `face_enhancement_creativity`。省略让 Topaz 自动配置。

face_enhancement_strength号码0 – 1

面部恢复强度（需要 face_enhancement=true）。

face_enhancement_creativity号码0 – 1

现实 (0) 到创意 (1) 面部恢复（需要 face_enhancement=true）。

锐化号码0 – 1

锐化强度。

降噪号码0 – 1

去噪强度。

fix_compression号码0 – 1

压缩伪影去除强度（仅限标准模型）。

强度号码0.01 – 1

整体模型强度（仅限标准模型）；太高可能看起来不切实际。

提示词字符串

描述生成模型的期望结果（不是 Wonder-3/wonder-3.5）；描述性陈述比指令更有效。不能与 autoprompt=true 结合使用。

自动提示词布尔值

自动生成指导提示（生成模型除了 Wonder-3/wonder-3.5；替换 `prompt`）。

创意整数1 – 9

生成创造力 1-9（仅限生成模型）； lower 保持最真实的输入。

纹理整数1 – 5

生成纹理细节 1-5（仅限生成模型）； 1 为低创造力，3 为较高创造力。

细节布尔值

添加渲染后细节（仅限生成模型）。如果为 true，则需要 `detail_strength`。

detail_strength号码0 – 10

渲染后细节强度（要求detail=true）。

enhancement_strengthenum

增强级别（仅限 Wonder-3 和 Wonder-3.5）；省略让 Topaz 自动配置。

接受的值

upscale_factor
model
output_format
subject_detection
enhancement_strength

输入模式

图片链接image_url

可直接使用公开链接。若文件在本地，先向 /v1/media/uploads 提交 { content_type, size_bytes }，再带上返回的请求头，使用 PUT 将图片上传至 upload_url，最后使用返回的 url。

返回一个工作对象状态，不是最终输出。存储响应中的 ID 并轮询作业直至完成。

民意调查状态

获取/v1/media/jobs/{request_id}

请求

curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
  -H "X-API-Key: YOUR_API_KEY"

返回数据

{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "running"
}

按 ID 轮询作业，直到达到最终状态：已完成或失败。已完成的作业在输出中携带其下载 URL，并且 GET /v1/media/jobs/{request_id}/content 返回与 { "url" } 对于只保留 ID 的客户端。

DELETE /v1/media/jobs/{request_id} 删除作业的存储介质以及提交时捕获的请求（提示和参数）。然后作业报告 deleted_at 并且没有输出，内容端点回答410。

作业对象

id字符串

作业的唯一标识符。

状态枚举

作业的状态。其中之一：

对象

生成输出。工作完成后立即出现。

错误字符串

如果作业失败，则失败的原因。

deleted_atnumber

当您删除作业的存储媒体时，以纪元秒为单位。在此之前为空，一旦设置后输出为空。

用法对象

提供者为作业报告的单位，例如 video_output_tokens 或 image_output_tokens。一旦作业终止就存在，仅携带作业报告的单位，并且当没有报告任何内容时为空。

对象

工作收费。工作结束后在场；提交响应和 webhooks 上为 null。

错误

在通话中共享

错误使用传统的 HTTP 状态代码以及形状的 JSON 主体 {"message": "..."}. 参数校验失败时返回 422 并带有一条命名有问题字段的消息。作业行存在后提交拒绝（余额、速率限制）返回失败的作业信封 — 分支 error.code.

状态	当	身体
401 未经授权	API 密钥丢失或无效。	{"message":"Invalid API key"}
403 禁止	非活动密钥被拒绝 {"message"} 身体。作业行存在并返回失败的作业信封后，组织余额或后付费周期限制无法覆盖的提交将被拒绝。 GET /billing/balance 将两者分开： 200 表示密钥处于活动状态，因此拒绝的是余额或循环限制。	{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}}
404 未找到	您的组织中不存在具有该 ID 的作业，或者媒体路径名称未知的供应商/型号/功能。	{"message":"media job not found"}
409冲突	在作业完成之前请求结果，或者将 Idempotency-Key 标头与不同的正文重用。	{"message":"media job is not ready"}
422 无法处理的实体	请求正文验证失败：枚举值无效、缺少必填字段、类型错误或 JSON 格式错误。 JSON 消息命名有问题的字段。无法定价的架构有效参数组合在创建作业后失败，并返回失败的作业信封和错误代码 invalid_input.	{"message":"duration: Input should be less than or equal to 15"}
429 请求太多	您已达到每分钟或每天的请求限制，或者您组织的作业队列已满。作为失败的作业信封返回。如果存在 Retry-After 标头，请等待那么长时间，然后使用新的 Idempotency-Key 重试。	{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}}
503服务不可用	模型导轨或后端依赖项暂时不可用。作为失败的作业信封退回；使用退避和新的幂等密钥重试。	{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}}

Topaz Image Upscale

能力

身份验证

端点

参考上传

生成

民意调查状态

错误

加入俱乐部