API reference

Create a video generation task

POST/v1/videos

Persistent background workers handle dispatch, polling, billing settlement, and saving. Client queries only observe status and do not trigger settlement. Ordinary and persistent requests follow their respective model/managed-frame/quote constraints. For unknown/submission_state_unknown, never blindly resend with a different request key.

Ordinary and persistent workflows

Ordinary videos use the model's public HTTPS inputs. Persistent videos use retention=persistent, a complete preset from the capability catalog, managed frames, and a valid quote. Do not mix workspace frame fields into ordinary requests or assemble parameters from different presets into a new combination.

Background processing advances execution, settlement, and saving; client queries only observe records. Estimated reservations may require an additional charge or a refund. If saving fails after success, retry archival of the original result rather than generating again. Recover unknown submissions with the original request key first; see Asynchronous tasks and idempotency.

Authentication and permissions

Use your current GloopAPI key. Available models, capabilities and permissions depend on its catalog and the endpoint documentation.

Authorization: Bearer $GLOOP_API_KEY

Authentication schemes: BearerAuth

Request

Request headers

Idempotency-KeystringRequired
Minimum length
1
Maximum length
191
Pattern
"^[\\x20-\\x7E]{1,191}$"

Request body · application/json

Type: object
Required fields: modelprompt
Additional properties: false

Request body required

modestringOptional
Required for persistent.

Enum
["text_to_video","image_to_video"]
retentionstringOptional
persistent uses the persistent workspace; omission creates an ordinary task.
quote_idstringOptional
New persistent requests must first confirm a valid quote returned by video-quotes.
start_frameobjectOptional
Required for persistent image-to-video: a managed file belonging to the same key. Prohibited for text-to-video.
start_frame child fields (1)
- file_idstringRequired
  Public ID of a managed file for the same account and key.
allOf branch 1
Type: object
Required in this branch: file_id
- file_idstringRequired
  Public ID of a managed file for the same account and key.
end_frameobjectOptional
Optional final frame for persistent; the capability must support it.
end_frame child fields (1)
- file_idstringRequired
  Public ID of a managed file for the same account and key.
allOf branch 1
Type: object
Required in this branch: file_id
- file_idstringRequired
  Public ID of a managed file for the same account and key.
webhook_endpoint_idstringOptional
Ordinary tasks may reference a receiver configured in the console; prohibited for persistent.
modelstringRequired
Public model ID from the current key's catalog; does not guarantee that a historical model remains available.
promptstringRequired
Generation prompt.

Minimum length
1
Maximum length
2500
durationintegerOptional
Model-specific duration in seconds. Use the complete combination from video-models mode.presets, not a Cartesian product. Wan Turbo does not support this field; there is no uniform default.
image_urlstringOptional
Model-specific public HTTPS first frame for ordinary tasks only; prohibited for persistent.
end_image_urlstringOptional
Model-specific public HTTPS final frame for ordinary tasks only; prohibited for persistent.
resolutionstringOptional
Resolution value in the model preset.
aspect_ratiostringOptional
Aspect ratio value in the model preset.
generate_audiobooleanOptionalAllows null
Model-dependent; use the mode's audio policy and presets. Do not assume every model generates audio.

Responses and errors

HTTP 202

The task was accepted; this does not mean it is complete.

application/json

Type: object
Required fields: idmodelstatuscreated_at

updated_atintegerOptional
Last update time in Unix seconds.
retentionstringOptional
Task result retention policy; persistent is the persistent workspace.
inputobjectOptional
Original task input or tool contract input.
input child fields (14)
- modestringOptional
  Required for persistent.
  
  Enum
  ["text_to_video","image_to_video"]
- retentionstringOptional
  persistent uses the persistent workspace; omission creates an ordinary task.
- quote_idstringOptional
  New persistent requests must first confirm a valid quote returned by video-quotes.
- start_frameobjectOptional
  Required for persistent image-to-video: a managed file belonging to the same key. Prohibited for text-to-video.
  start_frame child fields (1)
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
  allOf branch 1
  Type: object
  Required in this branch: file_id
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
- end_frameobjectOptional
  Optional final frame for persistent; the capability must support it.
  end_frame child fields (1)
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
  allOf branch 1
  Type: object
  Required in this branch: file_id
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
- webhook_endpoint_idstringOptional
  Ordinary tasks may reference a receiver configured in the console; prohibited for persistent.
- modelstringRequired
  Public model ID from the current key's catalog; does not guarantee that a historical model remains available.
- promptstringRequired
  Generation prompt.
  
  Minimum length
  1
  Maximum length
  2500
- durationintegerOptional
  Model-specific duration in seconds. Use the complete combination from video-models mode.presets, not a Cartesian product. Wan Turbo does not support this field; there is no uniform default.
- image_urlstringOptional
  Model-specific public HTTPS first frame for ordinary tasks only; prohibited for persistent.
- end_image_urlstringOptional
  Model-specific public HTTPS final frame for ordinary tasks only; prohibited for persistent.
- resolutionstringOptional
  Resolution value in the model preset.
- aspect_ratiostringOptional
  Aspect ratio value in the model preset.
- generate_audiobooleanOptionalAllows null
  Model-dependent; use the mode's audio policy and presets. Do not assume every model generates audio.
allOf branch 1
Type: object
Required in this branch: model, prompt
Additional properties: false
- modestringOptional
  Required for persistent.
  
  Enum
  ["text_to_video","image_to_video"]
- retentionstringOptional
  persistent uses the persistent workspace; omission creates an ordinary task.
- quote_idstringOptional
  New persistent requests must first confirm a valid quote returned by video-quotes.
- start_frameobjectOptional
  Required for persistent image-to-video: a managed file belonging to the same key. Prohibited for text-to-video.
  start_frame child fields (1)
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
  allOf branch 1
  Type: object
  Required in this branch: file_id
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
- end_frameobjectOptional
  Optional final frame for persistent; the capability must support it.
  end_frame child fields (1)
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
  allOf branch 1
  Type: object
  Required in this branch: file_id
  - file_idstringRequired
    Public ID of a managed file for the same account and key.
- webhook_endpoint_idstringOptional
  Ordinary tasks may reference a receiver configured in the console; prohibited for persistent.
- modelstringRequired
  Public model ID from the current key's catalog; does not guarantee that a historical model remains available.
- promptstringRequired
  Generation prompt.
  
  Minimum length
  1
  Maximum length
  2500
- durationintegerOptional
  Model-specific duration in seconds. Use the complete combination from video-models mode.presets, not a Cartesian product. Wan Turbo does not support this field; there is no uniform default.
- image_urlstringOptional
  Model-specific public HTTPS first frame for ordinary tasks only; prohibited for persistent.
- end_image_urlstringOptional
  Model-specific public HTTPS final frame for ordinary tasks only; prohibited for persistent.
- resolutionstringOptional
  Resolution value in the model preset.
- aspect_ratiostringOptional
  Aspect ratio value in the model preset.
- generate_audiobooleanOptionalAllows null
  Model-dependent; use the mode's audio policy and presets. Do not assume every model generates audio.
billingobjectOptional
Independent billing status; do not substitute generation status.
billing child fields (7)
- currencystringRequired
  Quote/billing currency.
- error_codestringOptional
  Public error code usable for branching logic.
- statusstringRequired
  Current object status; evaluate separately from billing and the saving stage.
- reserved_quotaintegerRequired
  Reserved quota in platform quota units, not a USD amount.
- final_quotaintegerRequiredAllows null
  Final charge in platform quota units; null means not yet determined.
- reserved_amountstringRequired
  Maximum reservation amount as a string in the quote currency.
- final_amountstringRequiredAllows null
  Final charge as a string; null means not settled.
allOf branch 1
Type: object
Required in this branch: currency, status, reserved_quota, final_quota, reserved_amount, final_amount
- currencystringRequired
  Quote/billing currency.
- error_codestringOptional
  Public error code usable for branching logic.
- statusstringRequired
  Current object status; evaluate separately from billing and the saving stage.
- reserved_quotaintegerRequired
  Reserved quota in platform quota units, not a USD amount.
- final_quotaintegerRequiredAllows null
  Final charge in platform quota units; null means not yet determined.
- reserved_amountstringRequired
  Maximum reservation amount as a string in the quote currency.
- final_amountstringRequiredAllows null
  Final charge as a string; null means not settled.
storageobjectOptional
Independent file saving status.
storage child fields (3)
- file_idstringOptional
  Public ID of a managed file for the same account and key.
- statusstringRequired
  Current object status; evaluate separately from billing and the saving stage.
- error_codestringOptional
  Public error code usable for branching logic.
allOf branch 1
Type: object
Required in this branch: status
- file_idstringOptional
  Public ID of a managed file for the same account and key.
- statusstringRequired
  Current object status; evaluate separately from billing and the saving stage.
- error_codestringOptional
  Public error code usable for branching logic.
availabilityobjectOptional
Current available actions.
availability child fields (4)
- can_cancelbooleanRequired
  Whether the current task allows requesting cancellation.
- can_deletebooleanRequired
  Whether the current task allows deletion.
- can_retry_storagebooleanRequired
  Whether the current task allows retrying a save.
- reasonstringOptional
  Public reason for an unavailable action or billing review.
allOf branch 1
Type: object
Required in this branch: can_cancel, can_delete, can_retry_storage
- can_cancelbooleanRequired
  Whether the current task allows requesting cancellation.
- can_deletebooleanRequired
  Whether the current task allows deletion.
- can_retry_storagebooleanRequired
  Whether the current task allows retrying a save.
- reasonstringOptional
  Public reason for an unavailable action or billing review.
idstringRequired
Public identifier of this object, used for its corresponding detail path.
modelstringRequired
Public model ID from the current key's catalog.
statusstringRequired
Ordinary and persistent task status; may be pending_dispatch/submitting/queued/processing/succeeded/failed/cancelled/unknown. A terminal state does not mean billing is settled or archival is ready.
created_atintegerRequired
Creation time in Unix seconds.
resultobjectOptional
Metadata for prepared results; may be absent before completion.
result child fields (8)
- file_idstringOptional
  Public ID of a managed file for the same account and key.
- storage_statusstringOptional
  File archival status; managed downloads are only guaranteed after ready.
- deliverystringOptional
  authenticated_content means the content path must be used; do not assume a direct URL exists.
- content_pathstringOptional
  Platform-authenticated content path; request binary content with the same key.
- urlstringOptional
  Access URL for a result or reference; signed URLs are only valid briefly.
- content_typestringOptional
  Result MIME type.
- file_namestringOptional
  Public download filename.
- file_sizeintegerOptional
  Result file size in bytes.
allOf branch 1
Type: object
- file_idstringOptional
  Public ID of a managed file for the same account and key.
- storage_statusstringOptional
  File archival status; managed downloads are only guaranteed after ready.
- deliverystringOptional
  authenticated_content means the content path must be used; do not assume a direct URL exists.
- content_pathstringOptional
  Platform-authenticated content path; request binary content with the same key.
- urlstringOptional
  Access URL for a result or reference; signed URLs are only valid briefly.
- content_typestringOptional
  Result MIME type.
- file_namestringOptional
  Public download filename.
- file_sizeintegerOptional
  Result file size in bytes.
errorstringOptional
Public failure category or error object.

HTTP 400

Invalid request parameters.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (3)
- messagestringRequired
- typestringRequired
  Enum
  ["new_api_error"]
- codestringRequired

HTTP 401

The key is missing, invalid, expired, or revoked.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (4)
- codestringOptional
- messagestringOptional
- typestringOptional
- request_idstringOptional

HTTP 402

Insufficient available account or key quota.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (3)
- messagestringRequired
- typestringRequired
  Enum
  ["new_api_error"]
- codestringRequired

HTTP 403

The current key lacks permission.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (3)
- messagestringRequired
- typestringRequired
  Enum
  ["new_api_error"]
- codestringRequired

HTTP 409

Request conflict, not ready, or submission unknown. Query the original record first; never blindly resend.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (3)
- messagestringRequired
- typestringRequired
  Enum
  ["new_api_error"]
- codestringRequired

HTTP 429

Request/queue rate limit.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (4)
- codestringOptional
- messagestringOptional
- typestringOptional
- request_idstringOptional

HTTP 500

Internal authentication or data storage failure.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (4)
- codestringOptional
- messagestringOptional
- typestringOptional
- request_idstringOptional

HTTP 503

Service, storage, pricing, or model temporarily unavailable.

application/json

Type: object
Required fields: error

errorobjectRequired
error child fields (3)
- messagestringRequired
- typestringRequired
  Enum
  ["new_api_error"]
- codestringRequired