快速开始

1. 准备 API Key

在控制台创建有余额、未过期并允许目标模型的 API Key。本文使用 default 分组常用模型。

在终端设置变量。下面是 Bash 写法；Windows PowerShell 使用 $env:HAMUBOX_API_KEY = '你的 API Key'。

export HAMUBOX_API_KEY='sk-your-api-key'

API Key 是账户消费凭证，不要写入网页源码、Git 仓库或分享给他人。第三方应用应在自己的服务端保管 Key。

2. 确认可用模型

curl --fail-with-body 'https://api.hamubox.com/v1/models' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"

在响应的 data[].id 中查找目标模型。空列表、无权限或模型未出现在列表中时，先检查 Key 与分组，不要反复提交生成任务。

3. 提交图片任务

curl --fail-with-body 'https://api.hamubox.com/v1/image/generations' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "一只红色茶壶放在白色桌面上，自然光，产品摄影，无文字",
    "aspect_ratio": "3:2",
    "resolution": "2k",
    "output_format": "png",
    "n": 1
  }'

响应示例：

{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "nano-banana-pro",
  "operation": "generate",
  "status": "queued",
  "progress": 0,
  "created_at": 1788627335
}

立刻保存 id。HTTP 200 和 queued 只表示已接受任务，不是图片已经生成成功。

4. 查询结果

curl --fail-with-body 'https://api.hamubox.com/v1/image/generations/task_example' \
  -H "Authorization: Bearer $HAMUBOX_API_KEY"

每隔 5 秒查询一次。queued、in_progress 时继续等待；completed 或 failed 时停止。

{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "nano-banana-pro",
  "operation": "generate",
  "status": "completed",
  "progress": 100,
  "created_at": 1788627335,
  "completed_at": 1788627378,
  "outputs": [
    {"object": "image.generation.output", "url": "https://example.com/result.png", "mime_type": "image/png"}
  ]
}

从 outputs[].url 读取图片地址并下载到自己的存储。示例中的 example.com 是占位地址，不能直接用于真实生成。

5. 改为视频任务

提交路径改成 /v1/video/generations，请求体使用：

{
  "model": "dreamina-seedance-2-0-ep",
  "prompt": "A slow aerial shot over a green valley at sunrise, natural light, steady camera.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "watermark": false
}

查询路径为 /v1/video/generations/{task_id}。从成功响应的 metadata.url 读取视频地址，不是图片的 outputs[]。

下一步：任务生命周期 · 参考素材 · 完整 Python 示例