Skip to main content
Generation and follow-up endpoints are asynchronous. A successful submit returns a task and job_id; it does not mean the media is ready. The production flow is:

​
Status values

completed and failed are terminal. Do not keep polling after either state.

​
Polling

Poll GET /v1/job/{job_id}. This request does not require an API key: the UUID is a private capability token.
  • Use a bounded wait and a non-zero interval; never tight-loop.
  • Persist job_id before starting the wait.
  • A client timeout does not cancel the server task. Resume polling the same job_id rather than submitting a replacement.
  • Move long waits to a background job instead of holding an interactive HTTP request open.
  • Keep the UUID out of browser URLs, analytics, and public logs.
A client timeout does not change the server task. It may complete after your wait ends, so return a pending state to your application and let a worker resume the same job_id.

​
Webhooks

Generation endpoints accept an optional callback URL. Use it when your application already has a durable background or event-processing architecture.
  • Return a successful response quickly and process media asynchronously.
  • Expect duplicate, delayed, or missing delivery and deduplicate by job_id.
  • Treat the callback as a notification, then fetch the canonical task with Get Task before persisting the final state.
  • Keep polling as a recovery path for a callback that never reaches your system.
Task callbacks do not currently provide a public signing secret. Keep the callback endpoint behind an unguessable path, accept only the expected method and content type, validate the payload shape, and rely on Get Task for the canonical result. Delivery timing and retries are not an exactly-once guarantee. Your handler must be safe to run more than once.

​
Retries and duplicate jobs

Legnext does not deduplicate submit requests by prompt. A repeated POST creates a new billable task.
  • Retry 429, transient 5xx, network failures, and timeouts with capped exponential backoff and jitter.
  • Do not retry 400, 401, 402, or 403 unchanged.
  • If submit returned a job_id, poll that task instead of resubmitting.
  • Use an application-level operation ID to prevent two workers from submitting the same user request.
If the submit connection fails before you receive a response, the outcome is ambiguous: the server may already have created a task. Legnext does not expose a client idempotency key, so your application must choose between risking a duplicate task and asking the user or worker to retry. See Errors & Handling for failure classes and client actions.

​
Persist outputs

Remote output URLs are delivery URLs, not permanent application storage. Copy completed media into storage you control before the retention window ends. See Output Storage.