API reference

Query video task status

GET/v1/videos/{task_id}

Query status. Generation success, billing.status, and storage.status must be evaluated independently. Valid keys with exhausted quota may query tasks; current model authorization is checked according to this implementation.

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

Path parameters

task_idstringRequired
Public ID of a task created with the same key.

Responses and errors

HTTP 200

Request succeeded.

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 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 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 404

Object or capability unavailable.

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 410

The video task was deleted (task_deleted) and can no longer be read.

application/json

Type: object
Required fields: error

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

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 502

Service response error.

application/json

Type: object
Required fields: error

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

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