Início rápido

Escolha um modelo e um endpoint no Catálogo e envie os dados de entrada necessários para o endpoint. Este exemplo inicia uma Task de texto para imagem com o Flux 2:

Uma requisição assíncrona aceita retorna 202 Accepted com um identificador de Tarefa:

Armazene id com o registro da sua aplicação. É o identificador estável usado para polling, suporte e reconciliação de callbacks.

Media Input Fields são os campos da solicitação que contêm URLs de mídia: campos de nível superior cujos nomes terminam em _url ou _urls, como image_url ou image_urls, a url de cada item de video_list e element_input_urls, element_input_video_urls e element_input_audio_urls de cada item de kling_elements. callback_url é um endpoint de entrega, não um Media Input Field. Cada valor de Media Input Field pode ser uma URL HTTPS pública ou um data URI no formato data:<mime>;base64,<data>, com até 10 MB por data URI. A RunAPI armazena cada data URI como um File Upload temporário que expira após uma hora e usa esse upload na Task. Um data URI que não pode ser armazenado retorna 422 com o código de erro invalid_media_input.

Os endpoints de edição do GPT Image aceitam apenas URLs HTTPS em source_image_urls. Para enviar uma imagem local a esses endpoints, crie primeiro um File Upload e passe a URL retornada.

Para arquivos maiores que 10 MB, crie primeiro um File Upload com POST /api/v1/files e passe a URL retornada. Um File Upload multipart ou com origem em URL aceita arquivos de até 50 MB. As URLs de File Upload também expiram após uma hora, então crie um novo File Upload para cada Task que começar depois desse período.

Os endpoints de criação de tarefas aceitam um cabeçalho opcional Idempotency-Key com um valor opaco de até 512 caracteres. Gere um valor para cada tarefa lógica e mantenha-o junto à requisição até confirmar se ela foi aceita.

Se um timeout ou falha de conexão deixar o resultado desconhecido, repita exatamente a mesma requisição de criação de Task com a mesma chave. O RunAPI retorna a Task original em vez de criar e cobrar por uma segunda. Reutilizar uma chave com uma requisição de criação de Task diferente retorna 409 Conflict. Gere uma nova chave para uma Task intencionalmente nova, e não use X-Client-Request-Id como essa chave.

Endpoints síncronos lentos normalmente mantêm a conexão aberta e retornam a mesma resposta terminal de antes. Nenhuma alteração de polling é necessária para integrações existentes.

Para um orçamento de conexão intencionalmente mais curto, envie Prefer: wait=N. Se a Task ainda estiver em execução após esse orçamento explícito, o RunAPI retorna 202 Accepted com o mesmo id da Task, uma URL Location opaca para recuperação e Retry-After com o atraso sugerido para a próxima consulta. Siga Location exatamente em vez de construir uma URL de resultado. Um Resultado de Task concluído preserva o status HTTP terminal, os cabeçalhos permitidos, o tipo de conteúdo e o corpo; decodifique response.body de acordo com response.content_type, que nem sempre é JSON.

Acrescente o identificador da Tarefa ao mesmo caminho do endpoint:

Continue enquanto status for processing. Use backoff limitado entre requisições em vez de realizar polling continuamente. Uma Task se torna terminal quando seu status é completed ou failed.

Uma resposta completed inclui o id da Task, o status terminal, os campos de resultado específicos do endpoint e usage.cost como um valor float USD dessa Task. Persista o resultado necessário e interrompa o polling. Consulte a Referência da API do endpoint para conhecer o formato exato do resultado em vez de presumir que todo endpoint de mídia retorna os mesmos campos.

Envelopes de Task de criação, processing e failed omitem usage.

Tarefas que exigem apuração final da cobrança com base na mídia permanecem em processing até que o valor final seja registrado. O callback de conclusão só é enviado após essa apuração; seu usage.cost corresponde ao valor retornado nas consultas subsequentes à tarefa. Dados contábeis ausentes não são informados como zero: a tarefa permanece em processing enquanto esses dados são conciliados. Uma cobrança confirmada de valor zero é retornada como usage.cost: 0.

Uma resposta failed inclui o id da Tarefa, o status terminal e um error gerado pelo RunAPI, quando disponível. Interrompa o polling, registre o identificador e o erro, e tente novamente somente quando sua aplicação tiver classificado a falha como transitória. Uma nova tentativa cria um novo identificador de Tarefa.

Adicione um callback_url HTTPS público à requisição de criação quando quiser que o RunAPI envie os eventos de callback documentados para aquele endpoint:

Cada corpo de callback corresponde a um evento de ciclo de vida na Referência da API do endpoint. Um callback completed compartilha usage.cost com a resposta de polling completed; callbacks de criação, processing e failed omitem usage. Callbacks terminais incluem os mesmos campos de resultado que as respostas de polling terminais; alguns endpoints também enviam callbacks processing documentados. Retorne uma resposta HTTP bem-sucedida rapidamente e mantenha o polling disponível para reconciliação quando a entrega estiver atrasada ou seu handler de callback estiver indisponível.

Leia Callbacks para criar um Segredo de Callback, verificar assinaturas e processar novas tentativas com segurança.

Use POST /api/v1/vidu/image_to_video com model: "vidu-q4-image-to-video" e first_frame_image_url. Use POST /api/v1/vidu/reference_to_video com model: "vidu-q4-reference-to-video", um prompt não vazio e 1–15 pedidos reference_image_urls. Recupere cada tarefa com GET em sua criação caminho seguido por /:id. As tarefas concluídas contêm uma matriz videos de URLs de resultados. Você também pode fornecer callback_url para conclusão notificações.

Ambos os endpoints aceitam o número inteiro duration_seconds de 3 a 16, padrão 5 e output_resolution de 540p, 720p, 1080p, 2k ou 4k, padrão 720p. audio é um booleano JSON, padrão true; explícito false desativa o áudio gerado. Os prompts aceitam até 20.000 personagens. O prompt de imagem para vídeo é opcional e o primeiro quadro determina sua proporção de aspecto. A referência ao vídeo aceita aspect_ratio de 16:9, 9:16, 1:1, 4:3 ou 3:4, padrão 16:9 e até 3 reference_audio_urls.

Use URLs de mídia HTTP(S) públicos. As imagens devem ser JPG/JPEG, PNG ou WEBP; a imagem do primeiro quadro não deve ter mais que 50 MB. Cada áudio de referência o arquivo deve ser MP3, ter de 3 a 12 segundos de duração e não ter mais que 50 MB. RunAPI verifica tipos de campos, esquemas de URL e contagens de referência. A geração o provedor verifica o formato, o tamanho e a duração do áudio da mídia remota de forma assíncrona. Mídia inválida pode causar falha na tarefa através do falha normal e fluxo de reembolso.

Preços de imagem para vídeo. Preços de referências para vídeo.