Before you start

Base URL: `https://x2v.light-ai.top`. Model discovery is public. Quote, submit, query, result, and workflow run endpoints require `Authorization: Bearer apikey_...`. Create an API key in your LightX2V account; never print or persist a user's key.

1. Discover a model and its current contract

curl -sS https://x2v.light-ai.top/api/v1/model/list
curl -sS 'https://x2v.light-ai.top/api/v1/model/specs?task=t2i'

Choose `model_cls` from the response. Treat `/api/v1/model/specs` as authoritative for required media, allowed parameters, and current constraints.

2. Quote without uploading media

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":"A paper-cut city at sunrise"}'

For media tasks, supply the `input_meta` fields described by OpenAPI and the selected live model spec; do not upload the source file only to obtain a quote.

3. Submit the task

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":"A paper-cut city at sunrise"}'

Save the returned `task_id`. For local media, use the OpenAPI `MediaInput` shape; public URLs use `{"type":"url","data":"https://..."}`.

4. Poll and download

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'

Poll with bounded intervals until `SUCCEED`, `FAILED`, or `CANCEL`. Use `output_video` for video tasks. A result URL is signed and temporary: download it promptly and never treat it as a permanent asset URL.

Timeout recovery

After a network timeout, query the existing task when you already have its `task_id`. If no `task_id` was returned and the request may have reached the service, do not automatically resubmit; report the outcome as unknown and require manual verification to avoid duplicate tasks and charges.