Saltar a la navegación

Subida de recursos

La mayoría de las generaciones hacen referencia a archivos multimedia mediante una URL pública. Si tus archivos aún no están alojados en un lugar público o quieres una referencia reutilizable que tenga en cuenta tu plan y puedas pasar a varios trabajos, súbelos a sync. labs como recursos y haz referencia a ellos por su id.

Para generar a partir de archivos locales grandes, se recomienda subirlos como recursos. Sube el archivo directamente al almacenamiento una vez. Después podrás reintentar una generación con el ID del recurso sin volver a enviar el archivo. La aplicación admite hasta 5 GiB por subida individual de recursos (5 × 1024³ bytes), siempre que el límite de tu plan lo permita. Las subidas multipart directas a POST /v2/generate tienen un límite de 5 GiB por archivo en el analizador de la aplicación y requieren mantener abierta la transferencia en cada solicitud. Los límites del proxy pueden ser menores, por lo que el límite del analizador no garantiza una transferencia directa de 5 GiB.

La subida consta de tres pasos.

  1. Solicita una URL prefirmada con POST /v2/assets/upload. Así indicas a sync. labs el nombre, el tipo y el tamaño del archivo.
  2. Envía los bytes del archivo sin modificar directamente a la URL prefirmada con un PUT HTTP sin encabezado de autenticación.
  3. Registra el recurso con POST /v2/assets. El endpoint verifica la subida, comprueba que el tamaño real del archivo se ajuste a los límites del plan y devuelve un id.

Luego usa el id devuelto como input[].assetId en una generación o como assetId de la muestra para clonar una voz.

Si tu archivo ya está alojado en una URL de acceso público, puedes omitir la firma y la subida con PUT y registrarlo directamente con POST /v2/assets. Consulta Cómo registrar una URL que ya es pública.

Cómo subir un recurso

1

Solicita una URL prefirmada

Llama a POST /v2/assets/upload con el fileName del archivo, su contentType (el tipo MIME, como video/mp4) y su size en bytes. Recibes una uploadUrl para enviar los bytes con PUT, la url canónica que registrarás en el paso 3 y expiresIn, que indica los segundos que faltan para que caduque la URL prefirmada.

curl -X POST https://api.sync.so/v2/assets/upload \
-H "x-api-key: $SYNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fileName": "speaker.mp4",
"contentType": "video/mp4",
"size": 8388608
}'

Una respuesta 201 tiene este aspecto.

{
"uploadUrl": "https://uploads.sync.so/...&X-Amz-Signature=...",
"url": "https://assets.sync.so/uploads/abc123/speaker.mp4",
"expiresIn": 3600
}
2

Envía el archivo con PUT a la URL prefirmada

Sube los bytes del archivo sin modificar mediante un PUT HTTP a uploadUrl. Omite tu x-api-key en esta solicitud. La URL ya está firmada. Trátala como una credencial temporal. Debes enviar el mismo Content-Type que declaraste en el paso 1 o se rechazará la subida.

curl
curl --fail-with-body --upload-file speaker.mp4 \
-H "Content-Type: video/mp4" \
"$UPLOAD_URL"

curl --upload-file envía un PUT y transmite el archivo desde el disco, de modo que los archivos grandes no tienen que caber en la memoria. Espera a que termine el PUT antes de registrar el recurso.

El encabezado Content-Type del PUT debe coincidir exactamente con el contentType que enviaste a /v2/assets/upload. Si no coincide o falta el encabezado, la subida no pasa la validación de firma. La URL prefirmada también caduca después de expiresIn segundos. Solicita otra si caduca.

3

Registra el recurso

Llama a POST /v2/assets con la url devuelta en el paso 1 y el type del recurso. El registro verifica que el archivo se haya subido y comprueba que el tamaño real del archivo respete los límites de tu plan. Una respuesta 201 devuelve un recurso con un id.

curl -X POST https://api.sync.so/v2/assets \
-H "x-api-key: $SYNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://assets.sync.so/uploads/abc123/speaker.mp4",
"type": "VIDEO",
"name": "Speaker take 1"
}'

Reutiliza un archivo que ya subiste

Antes de volver a subir el mismo archivo, llama a Buscar recurso subido con su resumen SHA-256 en contentSha256 y su type (VIDEO, AUDIO o IMAGE). El resumen debe contener 64 caracteres hexadecimales en minúscula. Incluye contentSha256 al registrar recursos con POST /v2/assets para encontrarlos más adelante.

La búsqueda devuelve el asset activo más reciente que coincide, o { "asset": null }. Solo busca entre los recursos registrados con la misma clave de API, incluso dentro de la misma organización. Si encuentras un recurso que coincide, reutiliza su id. Si no, sigue los pasos de subida anteriores.

Parámetros de la solicitud

POST /v2/assets/upload

fileName
stringRequired

El nombre del archivo que vas a subir, incluida la extensión (por ejemplo, speaker.mp4).

contentType
stringRequired

El tipo MIME del archivo (por ejemplo, video/mp4, audio/wav o image/png). Debes enviar este valor exacto en el encabezado Content-Type al enviar los bytes con PUT.

size
integerRequired

El tamaño del archivo en bytes. El límite por subida individual es de 5 GiB.

Devuelve 201 con uploadUrl (donde debes enviar los bytes con PUT), url (la URL canónica que debes registrar) y expiresIn (segundos hasta que caduque la URL prefirmada).

POST /v2/assets

url
stringRequired

La url que devuelve POST /v2/assets/upload o cualquier URL de acceso público si vas a registrar directamente un archivo que ya está alojado.

type
stringRequired

El tipo de recurso. Usa AUDIO, VIDEO o IMAGE.

name
string

Una etiqueta opcional que identifica el recurso con un nombre legible.

projectId
string

Un proyecto opcional al que vincular el recurso.

Devuelve 201 con el recurso registrado, incluido su id.

Usa un assetId en una generación

Cuando tengas el id de un recurso, indícalo en la matriz input de una generación con assetId en lugar de url. Puedes combinar entradas por ID de recurso y por URL en la misma solicitud.

curl -X POST https://api.sync.so/v2/generate \
-H "x-api-key: $SYNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "lipsync-2",
"input": [
{ "type": "video", "assetId": "asset_abc123" },
{ "type": "audio", "url": "https://assets.sync.so/docs/example-audio.wav" }
],
"options": { "sync_mode": "cut_off" }
}'

Para reintentar una generación, reenvía el mismo cuerpo de solicitud con el mismo encabezado Idempotency-Key. Puedes omitir la subida y el registro al reintentar. El id del recurso sigue siendo válido y puedes reutilizarlo en generaciones posteriores.

También puedes pasar el id de un recurso como muestra para clonar una voz (assetId) al crearla con POST /v2/voices. Consulta Clonación de voz.

Cómo registrar una URL que ya es pública

Si tu archivo multimedia ya está alojado en una URL de acceso público, omite los pasos de firma y de PUT y regístralo directamente. sync. labs obtiene el archivo para verificarlo y aplicar los límites del plan.

curl -X POST https://api.sync.so/v2/assets \
-H "x-api-key: $SYNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-cdn.com/clips/speaker.mp4",
"type": "VIDEO",
"name": "Speaker take 1"
}'

Importa el enlace a un vídeo de una red social

Pasa un enlace público a un solo vídeo de TikTok, Instagram, Facebook o YouTube a POST /v2/assets con type: "VIDEO". Sync importa el vídeo y devuelve un recurso reutilizable. También puedes usar el enlace en el campo url de vídeo o audio de una generación.

Mientras el recurso se importa, POST /v2/assets devuelve 409 con errorCode: "import_in_progress". Espera el tiempo indicado por Retry-After y vuelve a enviar la misma solicitud. La respuesta incluye importJobId, importStatus y el progreso cuando está disponible. Cuando termina la importación, la creación del recurso devuelve el recurso importado.

Una generación estándar con un vídeo enlazado puede aceptarse como PENDING mientras se importa. Las solicitudes con audio enlazado, las generaciones por segmentos y las solicitudes de doblaje devuelven 409 import_in_progress hasta que termina la importación. Para esas solicitudes, espera el tiempo indicado en Retry-After y reintenta con el mismo cuerpo y la misma Idempotency-Key, si la enviaste.

Una respuesta 429 indica que se alcanzó un límite de importaciones simultáneas o diarias. Respeta Retry-After o sube el archivo directamente. Si recibes 422 import_failed, lee el mensaje, comprueba que el enlace apunte a un solo vídeo público o usa la subida directa. 403 import_not_enabled indica que la importación de enlaces no está disponible para la cuenta. 503 import_unavailable indica que no está disponible temporalmente.

Límites de subida y de solicitudes

Máximo por subida individual5 GiB por archivo
Límite de solicitudes de URL prefirmadas120 solicitudes por minuto por clave de API en POST /v2/assets/upload
Comprobación del tamañoAl registrar el recurso, los límites del plan se comprueban con el tamaño real del archivo subido en vez del size declarado
Vigencia de la URL prefirmadaexpiresIn segundos (de la respuesta de /upload). Solicita una nueva si caduca.

Preguntas frecuentes

Si tu archivo multimedia aún no está alojado en una URL de acceso público, puedes subirlo para usarlo en una generación. Los recursos también son reutilizables. Registra el recurso una vez y usa el mismo id en varias generaciones o clonaciones de voz sin volver a subir ni alojar el archivo. El registro también valida el archivo y comprueba los límites de tamaño de tu plan. Así detectas archivos demasiado grandes o inaccesibles antes de enviar una generación.

Las dos causas más habituales son un Content-Type que no coincide o una URL caducada. El encabezado Content-Type de tu PUT debe coincidir exactamente con el contentType que enviaste a POST /v2/assets/upload. Si declaraste video/mp4, debes enviar el PUT con Content-Type: video/mp4. Comprueba también que no estás enviando el encabezado x-api-key en el PUT. La URL prefirmada lleva su propia firma y añadir encabezados de autenticación puede invalidarla. Las URL prefirmadas caducan después de expiresIn segundos. Si ha pasado demasiado tiempo, solicita otra URL y vuelve a intentarlo.

Se comprueban al registrar el recurso (POST /v2/assets). El paso /upload solo genera una URL firmada. sync. labs comprueba el tamaño real del archivo subido al registrarlo. Que se firmen la URL y se complete el PUT no garantiza que el archivo cumpla el límite de tu plan.

Recursos relacionados

  • Clonación de voz. Usa el assetId de un recurso subido como muestra para POST /v2/voices.
  • API de generación. Haz referencia a un recurso como input[].assetId en una generación con sincronización labial.
  • Formatos multimedia compatibles. Consulta los tipos de archivo y códecs admitidos para recursos de vídeo, audio e imagen.