开始前

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

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

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. 不上传媒体完成报价

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. 提交任务

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. 轮询并下载

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` 且请求可能已经到达服务，不得自动重提；应将结果标记为未知并要求人工核实，避免产生重复任务和扣费。