What Job States Should an API Gateway Expose for MiniMax H3 Video Generation and Editing?

An API gateway should generally expose six normalized job states for asynchronous MiniMax H3 video workflows: accepted, queued, running, succeeded, failed, and canceled. Optional conditions such as retrying, cancel_requested, expired, and unknown can preserve important operational detail. This is a recommended provider-agnostic gateway design—not an official MiniMax H3 schema. Before implementation, verify current upstream state names, transitions, polling behavior, error payloads, cancellation support, and output-retention rules in the official MiniMax documentation.

The Short Answer: Use a Stable Six-State Lifecycle

A stable gateway contract keeps application code from depending directly on provider-specific status vocabulary. It also gives operations teams consistent ways to measure queueing, processing, failures, cancellation, and cost across workflows.

The core lifecycle should be:

• accepted: The gateway has validated and durably recorded the request. Upstream work may not have been created yet.
• queued: The job exists but has not started active processing. This may represent a gateway queue or a verified upstream queue.
• running: Processing has started, based on a meaningful upstream signal or gateway-controlled execution state.
• succeeded: Processing completed successfully and the gateway has a valid result reference or confirmed result record.
• failed: Processing reached a confirmed failure that will not continue without another action.
• canceled: Cancellation reached a confirmed terminal outcome under the gateway contract.

Do not interpret an HTTP 2xx submission response as evidence that generation or editing succeeded. It normally confirms only that the API request was accepted or processed at the HTTP layer. The durable job resource must communicate what happened afterward.

Several optional conditions can make the contract more operationally precise:

• retrying indicates that the gateway is retrying a recoverable coordination operation, such as a status query. It should not imply that a new video job was submitted.
• cancel_requested records that cancellation was requested but has not yet been confirmed upstream.
• expired indicates that a previously available job record or output is no longer retrievable under the applicable retention policy.
• unknown means the gateway cannot currently determine the upstream outcome. It should trigger reconciliation rather than immediate resubmission.

These conditions should be added only when clients receive clear semantics and action rules. A larger vocabulary without defined behavior creates more ambiguity rather than more control.

Define Terminal States and the Actions Allowed in Every State

Every state needs an explicit answer to four questions: Is it terminal? Should the client continue polling? Can cancellation be requested? Is a result available?

The following matrix is implementation guidance for a gateway-owned contract. Actual actions depend on verified upstream behavior.

State	Terminal?	Poll?	Cancellation	Retry guidance	Result retrieval
accepted	No	Yes	May be allowed	Repeat submission only with the same idempotency key	No
queued	No	Yes	May be allowed	Do not create a second job	No
running	No	Yes	Only if supported; completion may race cancellation	Retry status checks, not the video operation	No
retrying	No	Yes, with backoff	Depends on the underlying job	Gateway-controlled retry only	No
cancel_requested	No	Yes	Already requested	Do not resubmit	No
succeeded	Yes	No	Not applicable	No processing retry	Yes, subject to retention
failed	Yes	No	Not applicable	A new attempt may be allowed after error evaluation	No successful result
canceled	Yes	No	Not applicable	A new job requires an explicit decision	No
expired	Yes	No	Not applicable	Reprocessing may be required	No longer available
unknown	Indeterminate	Yes, through reconciliation	Avoid assumptions	Do not automatically resubmit	Not until resolved

The distinctions among failed, canceled, expired, and unknown matter. A failure may require corrected input or a controlled retry. A canceled job reflects user or policy intent. An expired job may have completed earlier even though its output is no longer available. An unknown job has not yet reached a trustworthy conclusion.

If a client retries after a terminal failure, the API should make clear whether it is creating a new job or invoking a retry operation tied to the original job. That distinction affects lineage, audit history, and cost attribution.

Map MiniMax Responses Without Coupling Clients to Upstream Vocabulary

The gateway should maintain a mapping layer between verified MiniMax responses and its normalized lifecycle. Clients should branch on the normalized state, not on raw upstream strings.

For example, the mapping process can:

1. Receive an upstream status or callback.
2. Validate that the response belongs to the expected provider job.
3. Map the verified upstream value to a gateway state.
4. Validate that the resulting transition is allowed.
5. Append the transition to state history.
6. Publish the updated status or webhook event.

Retaining an upstream_state field can help with diagnostics, but it should be sanitized and treated as informational. It must not expose credentials, sensitive payload content, infrastructure details, or uncontrolled provider messages. Clients should not need to understand that field to operate correctly.

The mapping should be versioned. If upstream vocabulary or behavior changes, the gateway can update its mapping without forcing every client to rewrite workflow logic. A mapping version also helps operators explain why two jobs created at different times were interpreted differently.

Do not map an unfamiliar upstream value directly to failed. Use unknown or another explicit reconciliation condition until the gateway can determine the outcome. Likewise, do not infer succeeded solely because a status request returned successfully; the response must confirm job completion and provide or identify the expected output.

Token Forge Cloud offers access paths for several named model families, including MiniMax Hailuo 2.3 and MiniMax Speech 2.8. These access paths do not confirm MiniMax H3 availability or a specific H3 state mapping. Any H3 integration should be validated against current official documentation and observed API behavior.

Enforce Safe Transitions for Retries, Cancellation, and Ambiguous Outcomes

A state model is useful only if the gateway enforces valid transitions. Common forward transitions include accepted to queued, queued to running, and running to a terminal outcome. The gateway should reject or quarantine transitions that would incorrectly move a terminal job back into active processing.

Several failure cases require deliberate handling:

• Duplicate submissions: Accept an idempotency key and bind it to a canonical request fingerprint. A repeated request with the same key and equivalent content should return the existing gateway job. Reusing the key with materially different content should produce a conflict rather than silently creating work.
• Submission timeouts: A lost response does not prove that the upstream job was never created. Record the attempt and reconcile it before submitting again when the provider offers a reliable lookup mechanism.
• Cancellation races: A job can complete while cancellation is in flight. cancel_requested prevents the gateway from claiming cancellation before it is confirmed. Define whether a verified completion wins the race or whether completed output must be withheld under business policy.
• Delayed callbacks: Events can arrive late or out of order. Compare event versions or timestamps where trustworthy, and enforce transition rules rather than applying every callback blindly.
• Ambiguous provider responses: Move the job to unknown, retain diagnostic context, and schedule reconciliation. Automatic resubmission may create duplicate, potentially billable work.
• Invalid transitions: Record them as operational events. Do not overwrite the last trustworthy state merely to accommodate a malformed or unexpected response.

Retries must also distinguish control-plane work from model work. Retrying a failed status request is different from submitting the generation or editing operation again. Only the latter can create another processing job and associated cost.

Use One Lifecycle for Generation and Editing, With Operation-Specific Metadata

Generation and editing should normally share the same normalized lifecycle when both are asynchronous jobs with comparable submission, queueing, processing, and completion semantics. A shared lifecycle simplifies client libraries, dashboards, alerts, webhooks, and finance reporting.

Use an operation_type field to distinguish workflows, with values defined by the gateway rather than assumed from MiniMax. Operation-specific metadata can then carry the details needed for each request.

A generation job may reference validated input instructions and requested output attributes. An editing job may also need source-asset references, edit instructions, asset-validation outcomes, and lineage connecting the result to its source. Both can use the same states while retaining different metadata schemas.

Keep sensitive inputs out of routine status responses. Status resources usually need references, hashes, classifications, or redacted summaries rather than full prompts and source assets. Access to input and output references should follow the application’s authorization model.

Separate lifecycles are justified when verified behavior materially differs—for example, if one operation cannot be canceled, has a different result-retention model, or contains additional approval stages. Even then, preserve common state meanings where possible so that succeeded and failed do not mean different things across operations.

Design the Status Contract for Polling, Webhooks, Errors, and Reconciliation

A useful status response should give applications enough information to make the next decision without exposing implementation details. The following payload is illustrative gateway design, not an official MiniMax H3 response schema:

``json { "gateway_job_id": "job_...", "provider_job_id": "redacted-or-provider-reference", "operation_type": "generation-or-editing", "state": "running", "upstream_state": "sanitized-provider-value", "progress": null, "created_at": "timestamp", "updated_at": "timestamp", "started_at": "timestamp-or-null", "completed_at": null, "result": null, "error": null, "retry": { "recommended": false, "retry_after": null }, "correlation_id": "correlation_...", "state_history": [] } ``

Expose progress only when the upstream signal is genuine, sufficiently granular, and operationally meaningful. A synthetic percentage can mislead users if a video remains at one value for a long time or if processing restarts. When reliable progress is unavailable, state, queue age, and elapsed time are more honest signals.

For polling, return server guidance when possible and have clients use bounded exponential backoff with jitter. Polling should slow as a job runs longer, respect rate limits, and stop at terminal states. A client timeout should stop that client’s wait loop; it should not silently cancel or mark the underlying job as failed.

Webhooks can reduce polling load, but they need authenticated delivery, replay protection, event identifiers, and idempotent consumers. Because delivery can be delayed or fail, provide a status endpoint as the source for reconciliation. A webhook-plus-polling fallback is usually more resilient than relying exclusively on either mechanism.

Normalize errors into stable machine-readable categories such as invalid input, authentication failure, authorization failure, rate limiting, upstream rejection, processing failure, timeout, cancellation, expired output, and indeterminate state. Preserve sanitized upstream diagnostic context separately for troubleshooting. Error responses should indicate whether retry is appropriate and whether retrying would create a new job.

A reconciliation worker should periodically inspect jobs that have exceeded expected state dwell patterns, missed callbacks, or entered unknown. Its purpose is to recover trustworthy state—not to force every unresolved job into failure or submit replacement work automatically.

Measure Gateway Reliability and Apply an Operational Suitability Checklist

Production suitability depends less on the number of states than on whether the gateway measures and governs their behavior. Useful metrics include:

• Queue age, active run duration, and end-to-end completion time by operation and route
• State-transition latency and time spent in each non-terminal state
• Terminal outcome counts and rates, separated into succeeded, failed, canceled, and expired
• Jobs entering unknown, reconciliation age, and reconciliation outcomes
• Duplicate requests suppressed and duplicate upstream jobs detected
• Cancellation requests, confirmed cancellations, and completion-versus-cancellation races
• Webhook delivery attempts, acknowledgment outcomes, and fallback polling load
• Cost attribution by gateway job, operation type, route, tenant, and terminal outcome

Targets should be based on observed workloads and upstream behavior rather than assumed completion guarantees. Alerting should focus on deviations such as rising queue age, growing reconciliation backlogs, unusual transition patterns, or increased polling caused by webhook disruption.

Before adopting a gateway design, confirm that it provides:

• A documented normalized state vocabulary with clear terminal semantics
• A maintained mapping between verified upstream responses and gateway states
• Idempotent submission and a defined duplicate-request policy
• Validation for transitions, late events, and cancellation races
• Recovery behavior for timeouts, network failures, and indeterminate outcomes
• Stable error codes with sanitized diagnostic context
• Correlation IDs and append-only or otherwise auditable state history
• Access controls for job status, source assets, and generated outputs
• Explicit job-record and output-retention policies
• Per-job usage and cost attribution suitable for operational and finance review
• Polling and webhook patterns that remain manageable as job volume grows

Token Forge Cloud Managed Model APIs provide API-first model access and usage data, with a path toward private deployment when workloads become predictable. Token Forge Cloud treats different workload classes as distinct serving-policy problems, including routing and operational-control considerations. These capabilities can support gateway orchestration, but they do not imply MiniMax H3 support, hosting, or a verified H3 integration.

Contact Token Forge Cloud to discuss API access, private deployment, and LLM inference cost control.