Krea 2 Medium Turbo API 接入教程

TL;DR

Krea 2 Medium Turbo 已在 HiAPI 上线：输入文字，每次生成一张图，可选 8 种比例和 4 档 creativity。
每张 $0.0215，比例和创意度共用单价；价格与预算表列出了批量用量。
调用 POST /v1/tasks，读取 data.taskId，查询任务成功后从 data.output[0].url 保存图片。

它适合生成什么？

可以用来探索商品配图、室内氛围和电影宽幅场景。输入只需描述文字与构图设置；如果任务是修改一张已有商品照片，应选择接收图片的编辑模型。

Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen

用这个提示词生成 →

请求 aspect_ratio=2.35:1、creativity=low；展示文件 1568×672 PNG；按现价每张 $0.0215。链接只填入提示词，比例与创意度需手动选择。

这张图把高楼、霓虹与湿地倒影放进宽幅构图。它适合作为页面视觉方向的起点；选定后保存原文件，避免为了找回同一张图而再次提交任务。

浏览器和 API 分别怎么开始？

浏览器路线：

打开上面的预填链接，确认文字描述。
选择 2.35:1 和 low，查看本次生成费用。
提交生成，完成后下载图片；需要其他题材时换用场景提示词。

API 路线：

准备 HiAPI API Key，把示例中的 YOUR_API_KEY 替换为自己的密钥，并只在服务端保存。
将模型名放在请求体顶层，把 prompt、aspect_ratio 和 creativity 放进 input。
保存返回的 taskId，查询到成功状态后下载结果；连接中断时先查询原任务。

curl：提交任务，再查询结果

以下为 Bash / Git Bash 写法。YOUR_TASK_ID 和 IMAGE_URL 是响应结构中的占位内容；查询时换成提交返回的真实 taskId。

curl --fail-with-body -sS -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen",
      "aspect_ratio": "2.35:1",
      "creativity": "low"
    }
  }'

{"code":200,"data":{"taskId":"YOUR_TASK_ID"},"message":"success"}

curl --fail-with-body -sS 'https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "code": 200,
  "data": {
    "taskId": "YOUR_TASK_ID",
    "status": "success",
    "output": [{"type": "image", "url": "IMAGE_URL"}]
  },
  "message": "success"
}

提交返回的任务编号位于 data.taskId。查询成功的 HTTP 响应还要继续检查 data.status：只有 success 才读取 data.output，遇到 fail 则处理失败。图片地址是临时结果地址，应及时下载保存。

Python：提交、限时查询与保存

先在运行示例的环境安装 requests。代码沿用上面城市案例的提示词与参数，保存图片时不会向图片地址转发 API Key。

import time
import uuid
from pathlib import Path
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
request_id = str(uuid.uuid4())
body = {
    "model": "krea-2-medium-turbo",
    "input": {
        "prompt": "Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen",
        "aspect_ratio": "2.35:1",
        "creativity": "low",
    },
}

created = requests.post(
    API,
    headers={**HEADERS, "Idempotency-Key": request_id},
    json=body,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]
print("task_id:", task_id)
deadline = time.monotonic() + 300

while time.monotonic() < deadline:
    response = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
    response.raise_for_status()
    data = response.json()["data"]
    if data["status"] == "success":
        image_url = data["output"][0]["url"]
        download = requests.get(image_url, timeout=60)
        download.raise_for_status()
        Path("result-image").write_bytes(download.content)
        print("Saved result-image")
        break
    if data["status"] == "fail":
        raise RuntimeError(f"Task failed: {task_id}")
    time.sleep(3)
else:
    raise TimeoutError(f"Resume querying this task: {task_id}")

这里的 3 秒查询间隔和 300 秒等待窗口是客户端示例设置。等待窗口结束不等于任务失败，保留 taskId 后可以继续查询；网络超时也不要直接提交新的生成任务。request_id 应与业务请求一起保存，同一请求重试沿用同一个值，新任务使用新值。

哪些参数可以填写？

位置与字段	要求	取值或默认值
顶层 model	必填	`krea-2-medium-turbo`
input.prompt	必填	1–5000 字符
input.aspect_ratio	可选	1:1、4:3、3:2、16:9、2.35:1、4:5、2:3、9:16；默认 1:1
input.creativity	可选	raw、low、medium、high；默认 low
input.seed	可选	整数