To prevent duplicate AI video generation, preserve one durable identity for each intended generation, distinguish network attempts from provider jobs, and reconcile an uncertain submission before sending another. A client timeout tells you that the response did not arrive in time; it does not establish whether generation started.
Read first: review the lifecycle in AI video API architecture and the broader recovery categories in AI video API error handling.
Why a timeout creates uncertainty, not a confirmed failure
Consider a submission that crosses the network successfully. The provider accepts it, creates a job, and starts working. The response containing the job identifier is then lost. Your client reaches its timeout and shows an error, while the provider may already be generating the video.
If the application treats that error as proof that nothing happened, it may create a second job. Both jobs can eventually complete. The user wanted one video, but the system initiated two independent generations. Their outputs may differ even when the inputs match, and their billing treatment depends on the service’s actual rules.
Token360’s timeout and duplicate-work guidance explicitly warns against blindly retrying create or submit operations after ambiguous timeouts. It recommends checking available history or resources using correlation data. This article develops an application design around that principle; it does not claim Token360 exposes a universal idempotency header for video creation.
A useful state label is submission_unknown. It means the application lacks enough evidence to say “accepted” or “not accepted.” Preserve that uncertainty instead of silently converting it into a failed generation.
Separate generation intent, network attempt, and provider job
Use different records for different events. A generation intent represents what the user authorized. A network attempt represents a particular transmission. A provider job represents accepted work with its own resource identity. These relationships make duplicate work visible instead of hiding it behind a single status field.
| Record | Purpose | Example |
|---|
| Generation intent | One authorized creative operation | intent-017 |
| Submission attempt | One transmission and its observed outcome | attempt-001 timed out |
| Provider job | Accepted work that can be observed | A returned or reconciled resource ID |
| Delivery action | A downstream action such as saving or notifying | One export for an accepted output |
Persist the intent before starting the request. Attach attempt records to it, including timestamps, endpoint, model identifier, outcome, and any returned request or trace identifiers. Store provider identifiers when obtained. Avoid putting API keys or authorization headers in these records.
A request ID can help trace a transmission, but should not automatically be treated as the provider job ID. A timeout may leave you with neither. Likewise, a locally generated intent ID is not searchable upstream unless the service supports accepting and retrieving that correlation value.
Guard local submissions, but understand the boundary
At your application boundary, create the intent once and use an atomic ownership transition before dispatching it. Two workers reading an eligible record at the same time must not both independently decide they own the submission. A database uniqueness constraint, transactional state change, or coordinated queue consumer can enforce the rule appropriate to your architecture.
Disabling the Generate button helps prevent double-clicks, but is not the authoritative guard. A browser refresh, repeated HTTP request, or second worker can bypass a purely visual restriction. The server should recognize a repeated action token and return the existing intent rather than create another one.
Do not derive that token solely from prompt text. A user may intentionally request three variations from identical inputs. Those are three valid generation intents. A transport retry of the first variation should retain its identity; an explicitly authorized new variation should receive a new one.
Local ownership cannot make a remote side effect atomic with your database write. A worker may crash after the provider accepts a job but before the returned identifier is saved. Once its lease expires, a replacement worker still needs to reconcile the uncertain submission. Simply acquiring the lease again is not permission to submit another generation.
Use provider idempotency only when its contract is documented
An idempotency key is useful when the server explicitly recognizes it and defines what repeated requests mean. Sending an arbitrary header does not create that guarantee. Before relying on a provider’s implementation, verify supported operations, key scope, retention window, parameter matching, concurrent-request behavior, and how failed responses are handled.
As a concrete example from another API, Stripe documents idempotent request behavior, including parameter comparison and key retention considerations. That contract is specific to Stripe. It is an illustration of what to look for in documentation, not evidence that a video endpoint shares the same semantics.
If a video operation documents idempotent retries, retain the same key and the same applicable payload for retries of that operation, following its contract. Do not rotate the key on each timeout: that can make every retry look like a new operation. Do not assume the key remains effective indefinitely after the documented retention period.
If support is undocumented or absent, label your protection accurately: local duplicate-dispatch prevention plus reconciliation. That can reduce avoidable submissions, but it cannot promise exactly one remote generation across every network failure.
Follow a recovery decision tree after an uncertain submission
First, determine what evidence you actually possess. A recorded provider job ID usually allows observation of that existing resource through supported operations. A request ID without a job ID may support history lookup or investigation. A local timestamp and input fingerprint alone may be insufficient to identify one remote job confidently.
| Evidence after interruption | Recovery action |
|---|
| Known provider job ID | Resume observation of that job; do not recreate it. |
| Supported idempotency contract and valid retained key | Retry the same operation under the documented contract. |
| Correlation data and supported history lookup | Reconcile the original attempt before deciding on resubmission. |
| No trustworthy match | Keep the outcome unknown and escalate or request a deliberate decision. |
| Confirmed rejection before any work was accepted | Resolve the rejection, then follow the documented submission policy. |
A missing history entry is not automatically proof of non-acceptance. The lookup may be incomplete, delayed, or filtered to the wrong scope. Record the lookup boundary and evidence rather than treating one empty response as a definitive negative.
If the original outcome remains unknown and the user chooses to try again, make the tradeoff explicit: another job might be created while the first still exists. Record the new intent and its relationship to the unresolved one. This preserves a trail for later output review and billing reconciliation.
If two provider jobs are eventually discovered, keep both identifiers. Select which output to deliver using your workflow’s acceptance rules. Where cancellation is supported, confirm its actual outcome; requesting cancellation does not itself establish that work stopped or that charges disappeared.
Test failure windows with a local fake provider
The following six cases form an original test plan for the design. They have not been executed against Token360. A fake provider can count accepted jobs and deliberately interrupt responses, allowing you to test dangerous timing windows without generating paid videos.
| Injected event | Behavior to inspect |
|---|
| Two client requests carry the same action token | Both resolve to one local intent. |
| Two workers claim one eligible intent | Only one obtains dispatch ownership. |
| Provider accepts work but response is lost | Intent becomes unknown, not automatically eligible again. |
| Worker crashes before saving the returned job ID | Recovery reconciles the uncertain attempt. |
| The same completion event arrives twice | The intended downstream action is not duplicated. |
| User explicitly requests another variation | A new intent is permitted even with identical inputs. |
Record local intent count, transmission count, accepted provider-job count, unknown outcomes, and downstream delivery count separately. Three network attempts do not necessarily mean three accepted jobs; one local intent does not prove there was only one remote job.
For a purely illustrative accounting example, suppose 20 intended generations produce 23 confirmed accepted jobs, and every intent has at least one job. There are three excess accepted jobs, or 0.15 excess jobs per intent. That is not necessarily a 15% share of affected intents: the three extra jobs could belong to one, two, or three intents. Track the mapping before reporting an incident rate.
This arithmetic does not estimate charges. Reconcile actual billing records separately, including any failed work, cancellations, adjustments, or provider-specific charging rules. No savings or duplicate-job reduction has been measured for this article.
Make downstream processing safe to repeat too
Preventing duplicate submission is only one boundary. A completion can reach your application through both a webhook and a status check. A queue may redeliver processing work after a worker failure. Design the delivery step around a stable action identity, such as a particular export for a particular accepted output.
A single “handled” flag can be insufficient. If set before delivery, a crash may lose the action; if set afterward, a crash between delivery and the update can repeat it. Use durable action state and the receiving system’s documented deduplication support where available. Where atomicity across systems is impossible, retain enough evidence to reconcile an uncertain delivery instead of promising exactly-once effects.
Keep an operational queue for unresolved submissions and deliveries. Include the responsible owner, last observation, next reconciliation step, and age. The goal is not to hide uncertainty behind retries; it is to make uncertainty recoverable without multiplying work.
Retain these operational records under a defined access and retention policy. A correlation trail does not require copying every sensitive prompt or reference image into an unrestricted log. Store controlled references to the relevant input version, and preserve the identifiers needed to investigate an unresolved job.
FAQ
Does a video API timeout mean generation failed?
No. The provider may have accepted the job before the response was interrupted. Treat the result as uncertain until supported observations establish what happened.
Can I add an Idempotency-Key header to any video API?
Only rely on it when that operation documents support and semantics. An unsupported header may offer no protection against duplicate generation.
Should retries use the same generation intent ID?
Retries of the same authorized operation should remain associated with its original local intent. An intentional new variation should receive a new intent, even if the inputs are identical.
Is a prompt hash enough to detect duplicate requests?
No. Identical prompts can represent legitimate separate variations, while the complete generation recipe may also include references and model settings. Use an explicit action identity and retain the relevant input record.
What if I cannot find the original job?
Keep the submission marked unknown, investigate with available correlation evidence, and make any resubmission a deliberate decision. An empty lookup alone may not prove that no job exists.
Does this design guarantee exactly one generated video?
No universal guarantee follows from local guards alone. Remote idempotency, retention rules, failure recovery, and downstream delivery contracts determine which duplicate effects can actually be prevented.
Read next: coordinate notifications with AI video API webhooks and retain investigation evidence with AI API observability.
Tutorial
Tutorial
Tutorial