| Area | Implementation guidance |
|---|---|
| Request construction | Use exact model aliases and case-sensitive field names. Put documented controls under metadata. Keep ordered content roles intact. |
| Client records | Store public task ID, client_request_id, selected alias, intended settings, creation time, terminal state and final response. Keep your own business lineage if needed. |
| Authorization | Keep keys server-side. Retrieve tasks using the authorized owning key; do not treat shared organization membership as universal task access. |
| Retry | Use the same task ID for GET recovery. An ambiguous submit response is not permission to create a fresh job. See section 4. |
| Media access | Use stable, direct media URLs. Allow enough access time for validation, queueing and processing. Copy temporary results promptly. |
| Billing | Use the appropriate product model: native token/contract pricing, standalone enhancement seconds plus FPS band, Production combined seconds without an FPS band, or Seed Audio duration. |
| Playback | High-resolution or high-bit-depth output may need compatible codecs and players. Verify client playback requirements before selecting advanced controls. |
| Error parsing | Handle the standard error envelope and terminal task status. Do not depend on exact message wording or internal provider fields. |
{
"error": {
"message": "metadata.video_url must be a public HTTP or HTTPS URL.",
"type": "invalid_request_error",
"param": "metadata.video_url",
"code": "invalid_request_error"
}
}An HTTP success response from an asynchronous create endpoint indicates acceptance, not successful video delivery. Always use the terminal task result for delivery and reconciliation.
Maintenance, conflicts and task access
| Response / situation | Client action |
|---|---|
| HTTP 503 during scheduled maintenance | New video submissions may receive an English JSON maintenance message with Retry-After and Cache-Control: no-store. Respect Retry-After. Keep the original request and client_request_id if the POST outcome is uncertain. |
| Existing tasks during maintenance | Continue GET through the documented HTTPS endpoint. A service switch can briefly interrupt access; resume GET on the same task afterward. |
| HTTP 409: request ID reused with different parameters | An enhancement or Production request cannot redefine an accepted job by changing parameters under the same client_request_id. Use the original payload for replay, or a fresh ID only for an intentionally new job. |
| Task access denied after account/access changes | Retain the original task ID and contact LSF. Do not assume that a replacement key or changed access context can read every historical task. |
Parse the HTTP status, structured error when present and Retry-After. Do not match one exact English error sentence: messages can be clarified without changing the API contract.