Referência da API do Muse Video

Limites em resumo

Tudo o que o Muse Video aceita e tudo o que não aceita, numa única tabela. Confira antes de integrar o modelo: só 720p, só paisagem ou retrato, e um primeiro quadro ou até quatro imagens de referência, mas não os dois.

Valores e campos não suportados retornam 400 antes de a tarefa ser criada e não custam nada; as mensagens exatas estão em Erros, mais abaixo.

Nem toda requisição tem sucesso

Três modos de entrada

Um único id de modelo e um único endpoint; o modo depende das imagens que você envia. Os três custam o mesmo.

Um primeiro quadro e imagens de referência não podem ir na mesma requisição; enviar os dois retorna 400. Um array de imagens (images, image_urls ou reference_image_urls) sempre conta como imagens de referência, mesmo com um único item; para enviar um primeiro quadro, use o campo de imagem única image_url.

Início rápido

Todas as requisições levam a chave de API no cabeçalho:

Authorization: Bearer YOUR_API_KEY

Texto para vídeo

# Muse Video — text-to-video. model and prompt are required; everything else is optional.
# duration: whole seconds 4-30 (default 5). aspect_ratio: 16:9 (default, 1280x720) or 9:16 (720x1280).
# Billed $0.037 per requested second: this 10 s request is $0.37.
curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video",
    "prompt": "An orange cat stretches on a sunny windowsill, sunlight pours in, the camera slowly pushes in",
    "duration": 10,
    "aspect_ratio": "16:9"
  }'

# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "muse-video" } }

# Poll every 10-15 s until completed (result files are kept 30 days)
curl "https://api.apimodels.app/v1/video/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
# { "code": 200, "data": { "state": "completed",
#     "resultUrls": ["https://r2.apimodels.app/videos/clxxx.mp4"] } }

Imagem para vídeo (primeiro quadro)

Mesmo id de modelo e mesmo endpoint: acrescente uma imagem de primeiro quadro. Custa o mesmo que texto para vídeo. O exemplo em Node.js usa os nomes de campo no estilo OpenAI seconds, size e input_reference, que também funcionam.

# Muse Video — image-to-video: the same request plus ONE first-frame image.
# PNG, JPEG or WebP, up to 20 MB, as a public URL or a base64 data URI.
# Same price as text-to-video. Use an image with the same orientation as the clip.
curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video",
    "prompt": "She turns toward the window and smiles, the curtains drift in the breeze, slow push-in",
    "image_url": "https://example.com/first-frame-portrait.jpg",
    "duration": 6,
    "aspect_ratio": "9:16"
  }'

# first_frame_url, image or input_reference work in place of image_url. Do not put a first frame in image_urls:
# an image array (images, image_urls, reference_image_urls) always means reference images, see the next example.
# Poll the returned taskId exactly as in the text-to-video example.

Imagens de referência (até 4)

Para manter a mesma pessoa ou o mesmo elemento principal em vários clipes, coloque de 1 a 4 imagens de referência em images (image_urls e reference_image_urls também funcionam). O modelo mantém o rosto e a aparência, mas o clipe não começa a partir de nenhuma delas. Mencione no prompt "a mesma pessoa das imagens de referência" e depois descreva a cena nova. Não acrescente um primeiro quadro na mesma requisição; o preço é o mesmo de texto para vídeo.

# Muse Video — reference images: 1 to 4 images of the same person or subject in "images".
# The model keeps the face and look from them, but the clip does not start from any of them.
# image_urls and reference_image_urls work in place of images. Do not add a first frame to the same request.
# PNG, JPEG or WebP, up to 20 MB each, public URLs or base64 data URIs. Same price as text-to-video.
curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video",
    "prompt": "The same young woman from the reference images walks barefoot along a beach at sunset, smiling back at the camera, handheld vertical shot",
    "images": [
      "https://example.com/ref-1.jpg",
      "https://example.com/ref-2.jpg",
      "https://example.com/ref-3.jpg",
      "https://example.com/ref-4.jpg"
    ],
    "duration": 5,
    "aspect_ratio": "9:16"
  }'

# Poll the returned taskId exactly as in the text-to-video example.

Uma tarefa passa por pending → processing → completed ou failed. Em completed, data.resultUrls[0] é o MP4; em failed, o motivo está em data.failMsg e nada é cobrado. Clipes de até 10 segundos costumam levar de um a dois minutos, e os de 15 a 30 segundos, de três a sete; nossos pedidos de teste de 4 segundos no lançamento terminaram em cerca de 1.5 minuto. Consultar a cada 10-15 segundos é suficiente.

Callback (callback_url)

Para não precisar consultar, passe callback_url na requisição de criação. Quando a tarefa chega a completed ou failed, enviamos um HTTP POST (JSON) para essa URL. Entregas que falham são reenviadas com intervalos crescentes por até 30 minutos, até o seu endpoint responder com 2xx. A URL precisa ser acessível publicamente; localhost e endereços privados retornam 400 na criação. A consulta continua funcionando normalmente.

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "muse-video",
    "state": "completed",                 // or "failed"
    "param": "<JSON string>",             // your request, JSON.parse once
    "resultJson": "<JSON string> | null", // {"resultUrls": ["https://...mp4"]}, JSON.parse once
    "failCode": null,
    "failMsg": null
  }
}

Parâmetros

Não há entrada de último quadro, vídeo de referência nem áudio de referência, nem negative_prompt nem seed: enviar algum deles retorna 400, em vez de ser ignorado em silêncio. Também não há parâmetros de controle de câmera; descreva os movimentos de câmera no prompt.

A duração do clipe vem em degraus

Pedidos de 5, 6, 8, 10, 15, 20, 25 ou 30 segundos voltam exatamente com essa duração; qualquer outro número inteiro sobe para o próximo degrau, então o clipe nunca é mais curto do que o que você pagou. A cobrança segue os segundos pedidos, não a duração do clipe.

Tamanhos e saída

• Paisagem — aspect_ratio "16:9" ou size "1280x720" → 1280×720. É o padrão.
• Retrato — aspect_ratio "9:16" ou size "720x1280" → 720×1280.
• Não disponível — Quadrado, 1080p e qualquer outro tamanho: 400 antes de a tarefa ser criada.
• Saída — MP4 H.264, 24 fps, 720p. Os arquivos de resultado ficam guardados por 30 dias.
• Som — A Meta descreve o Muse Video como um modelo que gera o som junto com a imagem. Nos nossos testes de lançamento, dois pedidos de 4 segundos voltaram como dois clipes de 5.0 segundos: o de paisagem trazia uma faixa de áudio AAC e o de retrato veio sem som. Se o seu fluxo precisa de áudio, verifique se cada clipe tem faixa de áudio. O som não pode ser desligado: generate_audio: false retorna 400.

Primeiro quadro e imagens de referência

Primeiro quadro

• Apenas uma imagem, e o clipe começa a partir dela. Envie como image_url (first_frame_url, image ou input_reference também funcionam).
• Funciona melhor quando a imagem tem a mesma orientação do clipe: imagem em paisagem com 16:9, em retrato com 9:16.
• Só primeiro quadro, sem último quadro: enviar last_frame_url retorna 400.

Imagens de referência

• De 1 a 4 imagens no array images (image_urls e reference_image_urls também funcionam); mais de 4 retorna 400. Um array de imagens sempre é tratado como imagens de referência, nunca como primeiro quadro, mesmo com um único item.
• O modelo mantém a pessoa, o elemento principal ou o estilo delas (consistência de personagem), mas o clipe não começa a partir de nenhuma; a cena vem do prompt.
• Não podem ir na mesma requisição que um primeiro quadro; enviar os dois retorna 400.

Cada imagem

• Uma URL que qualquer pessoa consiga baixar diretamente, ou um data URI em base64 (data:image/png;base64,...). Para um arquivo local, você também pode enviá-lo pela Files API e usar a URL pública que ela devolve.
• PNG, JPEG ou WebP, até 20 MB cada. Um primeiro quadro em outro formato, ou acima de 20 MB, faz a tarefa falhar na execução, sem nenhuma cobrança.

Preços

A cobrança é pelos segundos solicitados: um pedido de 4 segundos custa $0.148 e devolve um clipe de 5 segundos. O primeiro quadro e as imagens de referência não custam nada a mais: os três modos têm o mesmo preço. Um pedido recusado com 400 não cria tarefa e não custa nada; gerações que falham não são cobradas.

Erros

Problemas de parâmetro voltam de forma síncrona como 400 na criação ({"code": 400, "msg": "..."}): nenhuma tarefa é criada e nada é cobrado. Os textos de msg abaixo são a redação atual; o nome do campo entre parênteses é o que você enviou.

• 401: a chave de API está ausente ou é inválida.
• 402: o saldo não cobre os segundos solicitados (segundos × $0.037).
• Um primeiro quadro em formato não suportado termina a tarefa em failed com data.failMsg first-frame image must be PNG, JPEG or WebP; um arquivo acima de 20 MB dá first-frame image is larger than 20 MB. Nenhum dos dois é cobrado.
• Outras falhas durante a geração (conteúdo recusado pelo modelo, um erro temporário de geração, tempo esgotado ou um clipe pronto descartado por orientação ou duração erradas) também terminam em failed com o motivo em data.failMsg, e não são cobradas. Veja "Nem toda requisição tem sucesso", mais acima.

Dicas

• Escreva três coisas no prompt: o que é o assunto, como ele se move e como a câmera se move. Por exemplo: "um gato laranja se espreguiça no parapeito da janela, a luz do sol entra, a câmera se aproxima devagar". Não há parâmetros de controle de câmera, então o prompt é a única forma de dirigi-la.
• Combine a orientação: primeiro quadro em paisagem com 16:9, em retrato com 9:16.
• Para um personagem recorrente, use imagens de referência: envie o mesmo conjunto de 1 a 4 fotos em cada clipe (de preferência com ângulos, expressões ou gestos diferentes), escreva no prompt "a mesma pessoa das imagens de referência" e depois descreva a cena nova. O primeiro quadro serve para "começar a partir desta imagem"; as referências, para "a mesma pessoa em outro lugar".
• Peça um dos degraus exatos (5, 6, 8, 10, 15, 20, 25 ou 30 segundos) para que a duração do clipe seja a que a sua edição espera.
• Clipes com mais de 10 segundos trocam de plano por volta dos 10 e dos 20 segundos, então escreva um prompt longo por trechos: "Primeiros 10 segundos: …, depois: …".
• Se o seu fluxo precisa de áudio, verifique antes se cada clipe tem faixa de áudio, por exemplo com ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 clip.mp4: ele imprime aac quando há faixa e nada quando o clipe está sem som.
• Os arquivos de resultado são apagados após 30 dias, então baixe ou hospede-os em outro lugar a tempo.
• Use apenas imagens (primeiro quadro ou referências) que você tenha direito de usar e, se aparecer alguém, com a permissão da pessoa.

Teste no Playground.

Relacionado