---

name: "serving" description: "Routes LightX2V FastAPI service workflows, task APIs, OpenAI-compatible image endpoints, queue inspection, and result download flows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Serving

Use this sub-skill for any LightX2V request that goes through the HTTP service stack instead of the direct pipeline.

Typical triggers

• "start the LightX2V server"
• "how do I call /v1/tasks or /v1/images?"
• "how do I poll task status or download the result?"
• "how do I stop a task?"
• "how do I use the sync image endpoint or presigned upload?"
• "how do I debug service status, queue pressure, or client disconnects?"

Read first

• references/api-reference.md for the endpoint map and request/response schemas.
• references/workflows.md for the standard start/submit/poll/download sequence and the OpenAI-compatible image flows.
• references/troubleshooting.md for the expected error codes and recovery steps.
• scripts/start_server.sh when you want a shell wrapper for the service entry point.
• ../../references/troubleshooting.md for cross-cutting import and dependency failures.

What belongs here

Include:

• python -m lightx2v.server
• ApiServer, TaskManager, FileService, and the generation service layer
• /v1/tasks, /v1/images, /v1/files, and /v1/service
• image and video queueing, polling, download, and stop flows
• OpenAI-compatible image generation and edit endpoints
• presigned upload handling for synchronous image tasks
• Gradio deployments that sit on top of the same serving stack

Exclude or route elsewhere:

• direct generation without the HTTP API → sub-skills/inference/
• controller / encoder / transformer / decoder deployment → sub-skills/disagg/
• LoRA, dummy-meta, and conversion helpers → sub-skills/conversion/

Safe starting checks

• python scripts/check_install.py
• python -m lightx2v.server --help
• python sub-skills/serving/scripts/check_status.py --url http://127.0.0.1:8000
• bash sub-skills/serving/scripts/start_server.sh --help

Guidance style

Prefer concrete, user-facing instructions:

• name the endpoint and the request type
• mention whether the request is synchronous or asynchronous
• show which fields are required for images, masks, video, audio, or presigned uploads
• state the expected status transitions and final download path
• call out when a response is JSON versus a binary image/video body

Decision points

When answering a serving question, separate the problem into these choices:

• transport: sync HTTP, async queue, or OpenAI-compatible endpoint
• media type: image, video, mask, or presigned upload response
• response shape: binary bytes, task JSON, download URL, or status JSON
• control action: poll, download, cancel, inspect queue, or inspect service metadata
• helper script: check_status.py, stop_task.py, post_image_task.py, post_video_task.py, post_openai_image.py, or start_server.sh

Common reminders:

• sync image calls only support n=1
• size strings must use WxH format for the OpenAI-compatible image API
• the result download route only works after the task reaches completed
• presigned uploads return JSON acknowledgment instead of raw image bytes
• the Gradio front-end is a convenience layer over the same serving stack

What a good answer should contain

For a future agent, a strong answer from this route should usually include:

• the endpoint name and method
• whether the flow is sync or async
• the required request fields and any size / format constraints
• the expected response shape, download path, or cancellation behavior
• the helper script that matches the exact flow, when one exists

If the request is really about how to generate a model output from local code, route back to inference; if it is about how the server accepts and serves that output, keep it here.