# LightX2V API 快速开始

> Documentation Index / 文档总索引  
> https://x2v.light-ai.top/llms.txt  
> Source: https://x2v.light-ai.top/api-docs#quick-start  
> Locale: zh-CN  
> 本页内容已为 Agent/LLM 阅读优化。

查询实时模型契约，完成报价、异步任务提交、状态轮询和结果下载。

## 开始前

Base URL：`https://x2v.light-ai.top`。模型发现接口公开；报价、提交、查询、结果和工作流运行接口需要 `Authorization: Bearer apikey_...`。请在 LightX2V 账号内创建 API Key，Agent 不得输出或持久化用户密钥。

## 1. 发现模型并读取当前契约

```bash
curl -sS https://x2v.light-ai.top/api/v1/model/list
curl -sS 'https://x2v.light-ai.top/api/v1/model/specs?task=t2i'
```
从响应中选择 `model_cls`。必需媒体、条件参数和当前限制以 `/api/v1/model/specs` 为准。

## 2. 不上传媒体完成报价

```bash
curl -sS -X POST https://x2v.light-ai.top/api/v1/billing/quote \
  -H 'Authorization: Bearer apikey_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"task":"t2i","model_cls":"MODEL_FROM_SPECS","stage":"single_stage","prompt":"日出时的剪纸城市"}'
```
媒体任务按 OpenAPI 和实时模型规格提供 `input_meta`；不要为了报价而上传或处理源文件。

## 3. 提交任务

```bash
curl -sS -X POST https://x2v.light-ai.top/api/v1/task/submit \
  -H 'Authorization: Bearer apikey_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"task":"t2i","model_cls":"MODEL_FROM_SPECS","stage":"single_stage","prompt":"日出时的剪纸城市"}'
```
保存返回的 `task_id`。本地媒体使用 OpenAPI 的 `MediaInput` 结构；公开 URL 使用 `{"type":"url","data":"https://..."}`。

## 4. 轮询并下载

```bash
curl -sS -H 'Authorization: Bearer apikey_YOUR_KEY' \
  'https://x2v.light-ai.top/api/v1/task/query?task_id=TASK_ID'

curl -sS -H 'Authorization: Bearer apikey_YOUR_KEY' \
  'https://x2v.light-ai.top/api/v1/task/result_url?task_id=TASK_ID&name=output_image'
```
按有限间隔轮询，直到 `SUCCEED`、`FAILED` 或 `CANCEL`。视频任务使用 `output_video`。结果地址带签名且会过期，应及时下载，不要保存为永久资源地址。

## 超时恢复

网络超时后，如果已有 `task_id`，必须先查询原任务。如果未返回 `task_id` 且请求可能已经到达服务，不得自动重提；应将结果标记为未知并要求人工核实，避免产生重复任务和扣费。

## Related / 相关主题

[authentication](/api-docs/authentication.md) · [model-discovery](/api-docs/model-discovery.md) · [task-api](/api-docs/task-api.md) · [workflow-api](/api-docs/workflow-api.md) · [errors](/api-docs/errors.md)

OpenAPI: https://x2v.light-ai.top/openapi.json · Live models: https://x2v.light-ai.top/api/v1/model/list · Skill: https://github.com/ModelTC/LightX2V-Skills
