教程

如何使用 krea-2-medium-turbo 文生图 API（curl + Python）

2026年11月3日

krea-2-medium-turbo 是 Krea 在 hiapi 上提供的快速、低成本文生图档位。你只需发送一个提示词、选择一个宽高比，就能通过异步任务 API 得到一张渲染好的图片。本指南提供可直接复制粘贴的 curl 和 Python 请求示例，针对 /v1/tasks，并给出确切的输入 schema，以及我在 2026-10-21 实测的耗时和错误行为——其中有一项结果与文档描述矛盾。

先决条件

一个 hiapi API 密钥（sk-...）。在 API Keys 控制台创建。每个请求都通过 Authorization: Bearer sk-<your-key> 进行认证。这是唯一的前提——模型在服务端运行，因此除了 HTTP 客户端之外无需安装任何东西。

输入 schema

krea-2-medium-turbo 接受五个字段。其中只有 prompt 和 model 是必填的：

字段	必填	类型	默认值	说明
`model`	是	string	—	必须完全是 `krea-2-medium-turbo`。
`prompt`	是	string	—	1–5000 个字符。
`aspect_ratio`	否	enum	`1:1`	`1:1`、`4:3`、`3:2`、`16:9`、`2.35:1`、`4:5`、`2:3`、`9:16` 之一。
`creativity`	否	enum	`low`	`raw`（最字面）→ `low` → `medium` → `high`（最有创意）。
`seed`	否	integer	—	可选。依赖它之前请先阅读下方的 seed 注意事项。

input 对象是严格的（additionalProperties: false）：任何不在此表中的字段都会在生成开始前被拒绝。没有 n / num_images，没有 resolution 或 size，也没有反向提示词字段。一次请求恰好返回一张图片，输出尺寸完全由 aspect_ratio 决定。如果你在 hiapi 上用过其他接受 resolution（Seedream、Qwen-Image）或 size 的图片 API，请在这些字段在此处去掉——它们会返回 400。

最小可用请求（curl）

创建任务会立即返回 taskId；图片在后台渲染。

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

响应：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" }, "message": "success" }

然后按 id 轮询任务，直到达到终态：

curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" \
  -H "Authorization: Bearer sk-<your-key>"

完成的任务如下所示（为清晰起见，字段有所删减）：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

图片位于 data.output[0].url。

Python 中的相同流程

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-<your-key>",
    "Content-Type": "application/json",
}

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # 轮询直到任务达到终态。
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # 注意：仍然是 HTTP 200，见下文
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

生产环境注意事项

轮询或使用回调。 上面的循环每 3 秒轮询一次，对低并发量没问题。在生产环境中，可在创建请求时附带 callback.url 并设置 when: "final"，让 hiapi 将完成的任务 POST 给你，而不是轮询——回调约定见 task API 文档。
生成失败仍返回 HTTP 200。 轮询端点上的 HTTP 状态码表示的是请求是否成功，而不是图片是否成功。渲染失败会以 200 和 data.status: "fail" 返回。请根据 data.status 分支，而不是根据 HTTP 状态码，否则你会把失败当作成功。
输出 URL 是临时的。 结果存储在 temp.hiapi.ai 上的 "storage": "temp" 下，并带有 expireAt 时间戳，大约七天后过期（我的运行中是 604,800 秒）。任务一完成就下载字节并重新托管（你自己的 bucket/CDN）——不要在生产页面中直接热链 temp.hiapi.ai 的 URL。
定价为每张图片单一固定费率，与宽高比或创意级别无关——无需考虑分辨率档位。请查看定价页面上的当前数字，而不是硬编码。

我实际测试的内容（2026-10-21）

以下全部来自实时调用，而非文档：

耗时和分辨率。 一个 2.35:1 请求约 26 秒完成（created → completed 的差值），返回的 PNG 为 1568 × 672 px——因此 2.35:1 确实是电影宽银幕裁剪，而不是近似方形。任务在渲染并将文件移至临时存储的过程中会经过中间状态 handling → archiving → success。
枚举校验在服务端强制执行。 发送 "aspect_ratio": "21:9"（一个看似合理但不支持的值）会立即返回 400：invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'。错误信息会指明字段并列出合法值，便于程序化处理。
未知字段返回 400，不会被忽略。 "resolution": "2K" 返回 invalid input: <root>: additional properties 'resolution' not allowed；"n": 2 对 n 返回同样的错误。这就是 additionalProperties: false 规则在起作用——从其他模型复制请求体，多余的字段会阻止整个调用。
在我的测试中，seed 未能复现完全相同的图片。 我连续两次发送相同的提示词、seed: 42、aspect_ratio: 2.35:1 和 creativity: medium。两次都返回了有效的 1568 × 672 图片，但明显是不同的场景（一张是白色塔楼，另一张是红白条纹塔楼），文件大小不同（1.30 MB 对 1.51 MB），哈希也不同。该字段被接受且被文档描述为可复现，但请将精确像素复现视为尽力而为而非保证——如果你需要特定画面，请保存你得到的结果，不要用 seed 重新请求。