# 快速开始

> 大约两分钟生成你的第一张图：创建 API Key、提交任务、读取结果。

## 创建 API Key

用邮箱收到的 6 位验证码登录[控制台](/console/api-keys)（第一次登录会自动创建账户），充值，然后在 **API → API Keys** 标签里新建一把 Key。完整的 Key 只在创建时显示一次，请保存到环境变量中。

```bash
export KEROX_API_KEY="kx_live_your_api_key_here"
```

## 提交任务

向 `https://api.kerox.ai/v1/tasks` 发送 `POST` 请求。传入 `wait_seconds: 30` 可让耗时较短的图片任务在一次请求内直接拿到结果；如果超时仍未结束，接口会返回当前的 `queued` 或 `running` 状态，你可以继续轮询或等待 Webhook 回调。

```bash
curl -X POST https://api.kerox.ai/v1/tasks \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedream-5.5",
    "input": {
      "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film",
      "size": "2K"
    },
    "wait_seconds": 30
  }'
```
```python
import os
import requests

resp = requests.post(
    "https://api.kerox.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "bytedance/seedream-5.5",
        "input": {
            "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film",
            "size": "2K",
        },
        "wait_seconds": 30,
    },
    timeout=60,
)
resp.raise_for_status()
task = resp.json()
print(task["id"], task["status"], task["output"])
```
```javascript
const res = await fetch('https://api.kerox.ai/v1/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bytedance/seedream-5.5',
    input: {
      prompt: 'editorial portrait of a ceramicist in morning sunlight, 35mm film',
      size: '2K',
    },
    wait_seconds: 30,
  }),
});

const task = await res.json();
console.log(task.id, task.status, task.output);
```

> **请在 7 天内保存生成结果**
>
> 生成的图片与视频链接会在任务完成 7 天后过期并删除（详见 `expires_at`），需要长期保留的文件请及时下载到你自己的存储空间。

## 读取结果

当 `status` 为 `"succeeded"` 时，生成文件会出现在 `output.images` 或 `output.videos` 中，`cost` 显示本次已结算的金额（即这张图的价格，当前价格见[模型页](/docs/models)）。若 `status` 仍为 `"queued"` 或 `"running"`，请轮询 `GET /v1/tasks/{id}` 或配置 Webhook。

```json
{
  "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V",
  "object": "task",
  "model": "bytedance/seedream-5.5",
  "status": "succeeded",
  "source": "api",
  "format": "native",
  "input": {
    "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film",
    "size": "2K"
  },
  "output": {
    "images": [
      {
        "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png",
        "content_type": "image/png",
        "width": 2048,
        "height": 2048
      }
    ]
  },
  "error": null,
  "cost": {
    "amount": "0.0280",
    "currency": "USD",
    "status": "settled"
  },
  "metadata": null,
  "warnings": [],
  "created_at": "2026-11-20T08:01:02Z",
  "started_at": "2026-11-20T08:01:02Z",
  "completed_at": "2026-11-20T08:01:10Z",
  "expires_at": "2026-11-27T08:01:10Z"
}
```

## 下一步

- [Webhook 回调](https://kerox.ai/docs/webhooks): 视频等长耗时任务完成时自动推送通知。
- [文件与输入](https://kerox.ai/docs/files): 上传参考图、视频首尾帧与音频文件。
- [MCP 服务](https://kerox.ai/docs/mcp): 让 Claude Code 或 Cursor 直接调用 Kerox。
