# 快速开始

## 创建 API 密钥

在[账户页面](/me?section=api-keys)创建密钥。网页、REST API 和 MCP 共用账户美元余额。密钥应保存在服务端。

```bash
export I2V_API_KEY="YOUR_API_KEY"
export I2V_BASE_URL="https://api.i2v.ai"
export IDEMPOTENCY_KEY="$(uuidgen)"
```

REST 请求使用 `https://api.i2v.ai`，任务接口位于 `/api/v1`。图像和视频模型见[公开媒体模型目录](/api/v1/generation-models)。`/api/v1/models` 用于查询 Chat Completions 模型。

要在 AI 客户端里生成媒体，请从 [MCP 客户端指南](/docs/mcp)开始。终端脚本和本地素材见 [CLI 与 Agent Skills](/cli)。要在自己的后端集成，请按下面的 REST 流程实操，并查看[可运行的 API 示例](https://github.com/i2v-ai/i2v-api-examples)。

要复用报价、恢复和签名回调的代码，请查看 [SaaS 与工作流接入](/docs/integration)。

## 选择模型

打开[模型文档](/docs/models)，选择图片或视频模型。每个模型页面提供公开模型 ID、输入参数、USD 价格，以及 cURL、Node.js 和 Python 提交示例。提交前请查看模型对参考图片和生成模式的要求。

## 获取报价并确认预算

向报价接口发送将要提交的模型和输入。报价不会创建任务或预占余额。检查返回的 `maximum.amount`，再设置你愿意为这次任务接受的美元上限。下面的命令需要 `jq`。

```bash
export I2V_MEDIA_REQUEST='{"model":"gpt-image-2","inputs":{"prompt":"A calm lake at sunrise"}}'
export I2V_QUOTE="$(curl --fail-with-body "$I2V_BASE_URL/api/v1/jobs/quote" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$I2V_MEDIA_REQUEST")"
printf '%s\n' "$I2V_QUOTE" | jq '{maximum, expectedRevision}'
```

## 提交生成任务

用十进制字符串填写 `I2V_MAX_COST_USD`。将报价中的 `expectedRevision` 与原始输入一起传给提交接口。如果目录版本或价格变化，请重新报价并核对预算。

```bash
export I2V_MAX_COST_USD="YOUR_APPROVED_USD_LIMIT"
export I2V_SUBMISSION="$(jq -ce \
  --arg cap "$I2V_MAX_COST_USD" \
  --argjson quote "$I2V_QUOTE" \
  'select($quote.expectedRevision | type == "number") |
   . + {maxCostUsd: $cap, expectedRevision: $quote.expectedRevision}' \
  <<< "$I2V_MEDIA_REQUEST")"
test -n "$I2V_SUBMISSION" && curl --fail-with-body "$I2V_BASE_URL/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data "$I2V_SUBMISSION"
```

受理成功后返回 `{"taskId":"YOUR_TASK_ID"}`。保存任务 ID、原幂等键和原请求体。提交响应丢失时，先用原凭据和相同幂等键[查询提交回执](/docs/media-workflow#丢失提交响应后的恢复)。如果需要重放同一个任务，请保留相同请求体和键。

## 查询生成结果

```bash
curl "$I2V_BASE_URL/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

| `status` | 含义 | 处理方式 |
| --- | --- | --- |
| `waiting` | 已受理并排队，尚未提交上游。 | 继续轮询。 |
| `generating` | 上游正在生成。 | 继续轮询；视频比图片慢。 |
| `success` | 已完成。 | 读取 `output[].url`。 |
| `fail` | 终态失败。 | 查看 `error.code` 与 `error.message`。 |

**轮询建议**

- 首次间隔 2–5 秒，之后按 1.5 倍递增，上限约 30 秒。
- 图片通常一分钟内返回；视频一般 1–5 分钟，长视频或上游繁忙时会更久。
- 只有 `waiting` 和 `generating` 表示仍在进行，`success` 或 `fail` 才应停止轮询。
- 始终查询同一个 `taskId`；轮询期间不要重复提交，否则会产生第二个计费任务。
- 客户端设置总超时（例如 30 分钟），超时后把任务 ID 返回给用户，而不是盲目重试。

成功响应示例：

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "gpt-image-2",
  "status": "success",
  "output": [{ "url": "https://file.example.com/generated/YOUR_TASK_ID/display.png" }],
  "billing": {
    "currency": "USD",
    "status": "captured",
    "charged": { "currency": "USD", "amount": "0.07200000" }
  },
  "createTime": 1763520000000,
  "completeTime": 1763520060000
}
```

失败响应示例（预扣已释放，不产生扣费）：

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "gpt-image-2",
  "status": "fail",
  "error": { "code": "generation_failed", "message": "Generation failed" },
  "billing": {
    "currency": "USD",
    "status": "released",
    "charged": { "currency": "USD", "amount": "0.00000000" }
  }
}
```

媒体任务成功后读取 `output[].url`。任务进行中或失败时，`output` 可能为 null。

[接口参考](/docs/api)提供完整响应结构。[任务回调](/docs/webhooks)介绍如何用签名事件替代轮询。提交响应丢失时，请按[错误与重试](/docs/errors)中的流程恢复。

参考[媒体接入与任务恢复](/docs/media-workflow)，了解签名上传、按请求获取美元报价，以及找回提交途中丢失的任务回执。