Referência da API

Criar tarefa de geração de vídeo

POST/v1/videos

Processos persistentes em segundo plano despacham, consultam, liquidam e salvam. Consultas do cliente apenas observam e não liquidam. Solicitações comuns e persistent seguem suas restrições de modelo/quadros gerenciados/cotação. Em unknown/submission_state_unknown, não reenvie às cegas com outra chave.

Fluxos comuns e persistentes

Vídeos comuns usam as entradas HTTPS públicas do modelo. Persistentes usam retention=persistent, preset completo do catálogo, quadros gerenciados e cotação válida. Não misture campos de quadros do espaço de trabalho em solicitações comuns nem combine parâmetros de presets diferentes.

O processamento em segundo plano avança execução, liquidação e salvamento; consultas do cliente só observam. A reserva estimada pode exigir cobrança adicional ou devolução. Se o salvamento falhar após o sucesso, tente arquivar o resultado original novamente, sem regenerar. Recupere primeiro envios desconhecidos com a chave original; consulte Tarefas assíncronas e idempotência.

Autenticação e permissões

Use sua chave atual do GloopAPI. Modelos, recursos e permissões disponíveis dependem do catálogo da chave e da documentação do endpoint.

Authorization: Bearer $GLOOP_API_KEY

Esquemas de autenticação: BearerAuth

Solicitação

Cabeçalhos da solicitação

Idempotency-KeystringObrigatório
Comprimento mínimo
1
Comprimento máximo
191
Padrão
"^[\\x20-\\x7E]{1,191}$"

Corpo da solicitação · application/json

Tipo: object
Campos obrigatórios: modelprompt
Propriedades adicionais: false

Corpo da solicitação obrigatório

modestringOpcional
Obrigatório em persistent.

Enumeração
["text_to_video","image_to_video"]
retentionstringOpcional
persistent usa o espaço persistente; omitir cria uma tarefa comum.
quote_idstringOpcional
Novas solicitações persistent precisam confirmar antes uma cotação válida de video-quotes.
start_frameobjectOpcional
Obrigatório em imagem para vídeo persistent: arquivo gerenciado da mesma chave. Proibido em texto para vídeo.
Campos filhos de start_frame (1)
- file_idstringObrigatório
  ID público de arquivo gerenciado da mesma conta e chave.
Ramificação allOf 1
Tipo: object
Obrigatório nesta ramificação: file_id
- file_idstringObrigatório
  ID público de arquivo gerenciado da mesma conta e chave.
end_frameobjectOpcional
Quadro final opcional em persistent, se o recurso oferecer suporte.
Campos filhos de end_frame (1)
- file_idstringObrigatório
  ID público de arquivo gerenciado da mesma conta e chave.
Ramificação allOf 1
Tipo: object
Obrigatório nesta ramificação: file_id
- file_idstringObrigatório
  ID público de arquivo gerenciado da mesma conta e chave.
webhook_endpoint_idstringOpcional
Tarefas comuns podem referenciar receptores do console; persistent proíbe.
modelstringObrigatório
ID público do catálogo da chave atual; não garante disponibilidade de modelos históricos do serviço.
promptstringObrigatório
Prompt de geração.

Comprimento mínimo
1
Comprimento máximo
2500
durationintegerOpcional
Segundos conforme modelo; use a combinação completa de video-models mode.presets, não produto cartesiano. Wan Turbo não aceita este campo; sem padrão uniforme.
image_urlstringOpcional
Quadro inicial HTTPS público específico do modelo para tarefas comuns; proibido em persistent.
end_image_urlstringOpcional
Quadro final HTTPS público específico do modelo para tarefas comuns; proibido em persistent.
resolutionstringOpcional
Resolução do preset do modelo.
aspect_ratiostringOpcional
Proporção do preset do modelo.
generate_audiobooleanOpcionalPermite null
Conforme modelo, política de áudio e presets do modo; não presuma que todos geram áudio.

Respostas e erros

HTTP 202

Tarefa aceita; não significa concluída.

application/json

Tipo: object
Campos obrigatórios: idmodelstatuscreated_at

updated_atintegerOpcional
Última atualização em segundos Unix.
retentionstringOpcional
Política de retenção do resultado; persistent é o espaço persistente.
inputobjectOpcional
Entrada original da tarefa ou do contrato da ferramenta.
Campos filhos de input (14)
- modestringOpcional
  Obrigatório em persistent.
  
  Enumeração
  ["text_to_video","image_to_video"]
- retentionstringOpcional
  persistent usa o espaço persistente; omitir cria uma tarefa comum.
- quote_idstringOpcional
  Novas solicitações persistent precisam confirmar antes uma cotação válida de video-quotes.
- start_frameobjectOpcional
  Obrigatório em imagem para vídeo persistent: arquivo gerenciado da mesma chave. Proibido em texto para vídeo.
  Campos filhos de start_frame (1)
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
  Ramificação allOf 1
  Tipo: object
  Obrigatório nesta ramificação: file_id
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
- end_frameobjectOpcional
  Quadro final opcional em persistent, se o recurso oferecer suporte.
  Campos filhos de end_frame (1)
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
  Ramificação allOf 1
  Tipo: object
  Obrigatório nesta ramificação: file_id
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
- webhook_endpoint_idstringOpcional
  Tarefas comuns podem referenciar receptores do console; persistent proíbe.
- modelstringObrigatório
  ID público do catálogo da chave atual; não garante disponibilidade de modelos históricos do serviço.
- promptstringObrigatório
  Prompt de geração.
  
  Comprimento mínimo
  1
  Comprimento máximo
  2500
- durationintegerOpcional
  Segundos conforme modelo; use a combinação completa de video-models mode.presets, não produto cartesiano. Wan Turbo não aceita este campo; sem padrão uniforme.
- image_urlstringOpcional
  Quadro inicial HTTPS público específico do modelo para tarefas comuns; proibido em persistent.
- end_image_urlstringOpcional
  Quadro final HTTPS público específico do modelo para tarefas comuns; proibido em persistent.
- resolutionstringOpcional
  Resolução do preset do modelo.
- aspect_ratiostringOpcional
  Proporção do preset do modelo.
- generate_audiobooleanOpcionalPermite null
  Conforme modelo, política de áudio e presets do modo; não presuma que todos geram áudio.
Ramificação allOf 1
Tipo: object
Obrigatório nesta ramificação: model, prompt
Propriedades adicionais: false
- modestringOpcional
  Obrigatório em persistent.
  
  Enumeração
  ["text_to_video","image_to_video"]
- retentionstringOpcional
  persistent usa o espaço persistente; omitir cria uma tarefa comum.
- quote_idstringOpcional
  Novas solicitações persistent precisam confirmar antes uma cotação válida de video-quotes.
- start_frameobjectOpcional
  Obrigatório em imagem para vídeo persistent: arquivo gerenciado da mesma chave. Proibido em texto para vídeo.
  Campos filhos de start_frame (1)
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
  Ramificação allOf 1
  Tipo: object
  Obrigatório nesta ramificação: file_id
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
- end_frameobjectOpcional
  Quadro final opcional em persistent, se o recurso oferecer suporte.
  Campos filhos de end_frame (1)
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
  Ramificação allOf 1
  Tipo: object
  Obrigatório nesta ramificação: file_id
  - file_idstringObrigatório
    ID público de arquivo gerenciado da mesma conta e chave.
- webhook_endpoint_idstringOpcional
  Tarefas comuns podem referenciar receptores do console; persistent proíbe.
- modelstringObrigatório
  ID público do catálogo da chave atual; não garante disponibilidade de modelos históricos do serviço.
- promptstringObrigatório
  Prompt de geração.
  
  Comprimento mínimo
  1
  Comprimento máximo
  2500
- durationintegerOpcional
  Segundos conforme modelo; use a combinação completa de video-models mode.presets, não produto cartesiano. Wan Turbo não aceita este campo; sem padrão uniforme.
- image_urlstringOpcional
  Quadro inicial HTTPS público específico do modelo para tarefas comuns; proibido em persistent.
- end_image_urlstringOpcional
  Quadro final HTTPS público específico do modelo para tarefas comuns; proibido em persistent.
- resolutionstringOpcional
  Resolução do preset do modelo.
- aspect_ratiostringOpcional
  Proporção do preset do modelo.
- generate_audiobooleanOpcionalPermite null
  Conforme modelo, política de áudio e presets do modo; não presuma que todos geram áudio.
billingobjectOpcional
Status de cobrança independente, não substituível pelo status de geração.
Campos filhos de billing (7)
- currencystringObrigatório
  Moeda da cotação/cobrança.
- error_codestringOpcional
  Código público de erro para decisões de fluxo.
- statusstringObrigatório
  Status atual do objeto; avalie separadamente da cobrança e do salvamento.
- reserved_quotaintegerObrigatório
  Reserva em unidades quota da plataforma, não em USD.
- final_quotaintegerObrigatórioPermite null
  Cobrança final em unidades quota da plataforma; null indica ainda não determinada.
- reserved_amountstringObrigatório
  Reserva máxima como string na moeda cotada.
- final_amountstringObrigatórioPermite null
  Cobrança final como string; null indica não liquidada.
Ramificação allOf 1
Tipo: object
Obrigatório nesta ramificação: currency, status, reserved_quota, final_quota, reserved_amount, final_amount
- currencystringObrigatório
  Moeda da cotação/cobrança.
- error_codestringOpcional
  Código público de erro para decisões de fluxo.
- statusstringObrigatório
  Status atual do objeto; avalie separadamente da cobrança e do salvamento.
- reserved_quotaintegerObrigatório
  Reserva em unidades quota da plataforma, não em USD.
- final_quotaintegerObrigatórioPermite null
  Cobrança final em unidades quota da plataforma; null indica ainda não determinada.
- reserved_amountstringObrigatório
  Reserva máxima como string na moeda cotada.
- final_amountstringObrigatórioPermite null
  Cobrança final como string; null indica não liquidada.
storageobjectOpcional
Status independente de salvamento.
Campos filhos de storage (3)
- file_idstringOpcional
  ID público de arquivo gerenciado da mesma conta e chave.
- statusstringObrigatório
  Status atual do objeto; avalie separadamente da cobrança e do salvamento.
- error_codestringOpcional
  Código público de erro para decisões de fluxo.
Ramificação allOf 1
Tipo: object
Obrigatório nesta ramificação: status
- file_idstringOpcional
  ID público de arquivo gerenciado da mesma conta e chave.
- statusstringObrigatório
  Status atual do objeto; avalie separadamente da cobrança e do salvamento.
- error_codestringOpcional
  Código público de erro para decisões de fluxo.
availabilityobjectOpcional
Ações disponíveis atualmente.
Campos filhos de availability (4)
- can_cancelbooleanObrigatório
  Se a tarefa atual permite solicitar cancelamento.
- can_deletebooleanObrigatório
  Se a tarefa atual permite exclusão.
- can_retry_storagebooleanObrigatório
  Se a tarefa atual permite tentar salvar novamente.
- reasonstringOpcional
  Motivo público de ação indisponível ou revisão de cobrança.
Ramificação allOf 1
Tipo: object
Obrigatório nesta ramificação: can_cancel, can_delete, can_retry_storage
- can_cancelbooleanObrigatório
  Se a tarefa atual permite solicitar cancelamento.
- can_deletebooleanObrigatório
  Se a tarefa atual permite exclusão.
- can_retry_storagebooleanObrigatório
  Se a tarefa atual permite tentar salvar novamente.
- reasonstringOpcional
  Motivo público de ação indisponível ou revisão de cobrança.
idstringObrigatório
Identificador público do objeto, usado na sua rota de detalhes.
modelstringObrigatório
ID público do modelo no catálogo da chave atual.
statusstringObrigatório
Status comum/persistente: pending_dispatch/submitting/queued/processing/succeeded/failed/cancelled/unknown. Estado terminal não implica liquidação nem arquivamento ready.
created_atintegerObrigatório
Data de criação em segundos Unix.
resultobjectOpcional
Metadados de resultados prontos; podem não existir antes da conclusão.
Campos filhos de result (8)
- file_idstringOpcional
  ID público de arquivo gerenciado da mesma conta e chave.
- storage_statusstringOpcional
  Status de arquivamento; download gerenciado garantido apenas após ready.
- deliverystringOpcional
  authenticated_content exige o caminho de conteúdo; não presuma a existência de URL direta.
- content_pathstringOpcional
  Caminho de conteúdo autenticado pela plataforma; solicite binário com a mesma chave.
- urlstringOpcional
  URL de acesso ao resultado ou referência; assinadas só valem temporariamente.
- content_typestringOpcional
  Tipo MIME do resultado.
- file_namestringOpcional
  Nome público do arquivo baixado.
- file_sizeintegerOpcional
  Bytes do arquivo de resultado.
Ramificação allOf 1
Tipo: object
- file_idstringOpcional
  ID público de arquivo gerenciado da mesma conta e chave.
- storage_statusstringOpcional
  Status de arquivamento; download gerenciado garantido apenas após ready.
- deliverystringOpcional
  authenticated_content exige o caminho de conteúdo; não presuma a existência de URL direta.
- content_pathstringOpcional
  Caminho de conteúdo autenticado pela plataforma; solicite binário com a mesma chave.
- urlstringOpcional
  URL de acesso ao resultado ou referência; assinadas só valem temporariamente.
- content_typestringOpcional
  Tipo MIME do resultado.
- file_namestringOpcional
  Nome público do arquivo baixado.
- file_sizeintegerOpcional
  Bytes do arquivo de resultado.
errorstringOpcional
Categoria pública de falha ou objeto de erro.

HTTP 400

Parâmetros de solicitação incorretos.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (3)
- messagestringObrigatório
- typestringObrigatório
  Enumeração
  ["new_api_error"]
- codestringObrigatório

HTTP 401

A chave está ausente, inválida, expirada ou revogada.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (4)
- codestringOpcional
- messagestringOpcional
- typestringOpcional
- request_idstringOpcional

HTTP 402

Cota disponível insuficiente na conta ou chave.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (3)
- messagestringObrigatório
- typestringObrigatório
  Enumeração
  ["new_api_error"]
- codestringObrigatório

HTTP 403

A chave atual não tem permissão.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (3)
- messagestringObrigatório
- typestringObrigatório
  Enumeração
  ["new_api_error"]
- codestringObrigatório

HTTP 409

Conflito, não pronto ou envio desconhecido; consulte o original primeiro, sem reenviar às cegas.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (3)
- messagestringObrigatório
- typestringObrigatório
  Enumeração
  ["new_api_error"]
- codestringObrigatório

HTTP 429

Limite de solicitações/fila.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (4)
- codestringOpcional
- messagestringOpcional
- typestringOpcional
- request_idstringOpcional

HTTP 500

Falha interna de autenticação ou armazenamento de dados.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (4)
- codestringOpcional
- messagestringOpcional
- typestringOpcional
- request_idstringOpcional

HTTP 503

Serviço, armazenamento, preços temporariamente indisponíveis.

application/json

Tipo: object
Campos obrigatórios: error

errorobjectObrigatório
Campos filhos de error (3)
- messagestringObrigatório
- typestringObrigatório
  Enumeração
  ["new_api_error"]
- codestringObrigatório