DocsAPIIntegraciones

Integraciones y API de Ads Studio

Cómo conectar Ads Studio de forma segura: emitir claves, trabajar con proyectos, iniciar generación, consultar estado y descargar resultados.

Gestionar integraciones Docs del estudio Abrir estudio

Modelo general

La API usa las mismas entidades que la interfaz:

Project — proyecto de anuncios (formato, duración, objetivo, materiales).
Job — job de generación creado a partir de un proyecto (en cola → en proceso → listo/error).
Outputs — resultados del job (por ejemplo, video final). Los enlaces son URLs firmadas temporales.

Importante

Los enlaces firmados no se guardan en la base de datos y se regeneran cada vez que se consulta un job. Para obtener un enlace actualizado, vuelve a pedir el estado del job.

Seguridad y acceso

Las integraciones funcionan en el contexto de un espacio de equipo (company/space). Esto significa:

Todas las solicitudes requieren el header x-ads-tenant-id — identificador del espacio.
Las claves API usan el header x-ads-api-key.
Crear y revocar claves está disponible solo para roles owner y admin.

Las claves no se guardan en texto plano

En la base se almacena solo el hash. El valor de la clave se muestra una sola vez al crearla — guárdalo de forma segura.

Cuota y control

Las claves API tienen límite adsApiCallsMonthly. Si se supera, devuelve HTTP 429.

Gestión de claves (en la UI)

En la consola de empresa abre: Integraciones. Ahí puedes crear/revocar claves y ver su nombre y huella (prefix/last4).

En la UI estas llamadas pasan por el proxy Ads UI → Ads API:

GET /api/space/keys → Ads API /api/ads/keys
POST /api/space/keys → Ads API /api/ads/keys
POST /api/space/keys/<id>/revoke → Ads API /api/ads/keys/<id>/revoke

Flujo del proyecto y generación

Orden recomendado para integraciones:

Paso 1

Encontrar projectId

Las integraciones suelen trabajar con proyectos existentes (creados en la UI). Obtén la lista con GET /api/ads/projects.

Paso 2

Iniciar generación

Crea un job con POST /api/ads/generate. La respuesta incluye jobId y estado queued.

Paso 3

Leer estado y descargar resultados

Consulta el job con GET /api/ads/jobs/<jobId> o la lista de jobs del proyecto GET /api/ads/projects/<projectId>/jobs. La respuesta contiene outputs con URLs firmadas.

Ejemplos de solicitudes (curl)

En todos los ejemplos sustituye:

TENANT_ID — identificador del espacio
API_KEY — clave de integración

1) Lista de proyectos

curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/projects

2) Iniciar generación

curl -s   -X POST   -H "content-type: application/json"   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   -d '{
    "projectId": "PROJECT_ID",
    "brief": "Oferta corta y requisitos del video",
    "durationSec": 12,
    "aspect": "9:16"
  }'   https://YOUR_ADS_API_HOST/api/ads/generate

3) Consultar estado del job

curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/jobs/JOB_ID

4) Lista de jobs del proyecto

curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/projects/PROJECT_ID/jobs

Subida de materiales (flujo UI)

En la UI, la subida funciona con un mecanismo presign seguro:

Ads UI solicita presign: POST /api/uploads/presign
Recibe uploadUrl y key
Sube el archivo directamente al storage con PUT uploadUrl
Adjunta la key al proyecto: POST /api/projects/<id>/assets

Comprobaciones de seguridad

El servidor acepta solo keys como projects/<projectId>/<kind>/<uuid>.<ext>. Esto evita adjuntar archivos fuera de la carpeta del proyecto.

¿Listo para conectar una integración?

Crea una clave en la consola de empresa y empieza listando proyectos y lanzando tu primer job.

Integraciones Proyectos