Conceptos básicos

Unas pocas palabras aparecen en todas partes en UnifAPI. Apréndelas una vez y el resto de la documentación se lee más rápido.

Skill

Un flujo de trabajo específico de una tarea que un agente puede ejecutar con UnifAPI MCP. Una Skill parte de una salida deseada, como un brief de fijación de precios de KOL o una lista corta de creadores, y luego permite al agente descubrir y llamar a operaciones de datos públicos cuando necesita evidencia.

Las Skills son el punto de partida recomendado para los usuarios de agentes. La referencia de la API es la capa de datos que las sustenta.

Proveedor

La plataforma pública desde la que una API expone datos: por ejemplo TikTok, Twitter/X, LinkedIn, YouTube, Reddit o Instagram. Cada proveedor tiene un prefijo de ruta de nivel superior.

https://api.unifapi.com/tiktok/...

Operación

Un único endpoint de datos públicos invocable dentro de un proveedor: por ejemplo GET /tiktok/videos/{id}. Cada operación tiene su propia página en la referencia de la API, y MCP expone el descubrimiento de operaciones mediante list_operations y get_operation.

Esquemas canónicos

Cada operación que devuelve el mismo tipo de recurso —un Video, un User, un Comment— usa el mismo esquema canónico. Así, GET /tiktok/videos/{id} y GET /tiktok/users/{id}/videos devuelven ambos objetos Video con nombres de campo y tipos idénticos.

Las formas canónicas viven en components.schemas de la especificación OpenAPI e incluyen: Video, Author, Music, MusicDetail, Comment, User, Hashtag, LiveRoom.

Identificadores

Los IDs son cadenas opacas. Parecen números largos, pero trátalos como cadenas para preservar la precisión (algunos son > 2^53).

• El id de usuario de TikTok (sec_uid) es un token base64 largo, p. ej. MS4wLjABAAAA....
• Los ids de vídeo, música y hashtag de TikTok son cadenas de aspecto numérico. Los endpoints de usuario de TikTok aceptan el handle público, el id de usuario numérico o el sec_uid donde sea compatible.

Resuelve un nombre de usuario a un id de usuario estable con /tiktok/users/resolve?username=jennmelon. Resuelve una URL de compartir a un vídeo con /tiktok/videos/resolve?url=....

Envelope de respuesta público

Las respuestas correctas usan el mismo envelope de nivel superior:

{
  "request_id": "req_...",
  "data": {
    /* resource or list payload */
  },
  "pagination": {
    "cursor": "1711494099000",
    "has_more": true
  },
  "billing": {
    "credits_charged": 10,
    "records_charged": 10,
    "balance_remaining": 90,
    "truncated_due_to_balance": false
  }
}

• request_id — el id de solicitud de UnifAPI para soporte y trazabilidad.
• data — la carga útil de negocio.
• pagination — presente cuando una operación de lista puede continuar.
• billing — créditos y registros cobrados por la llamada.

Paginación

• pagination.has_more — true cuando existe al menos una página más.
• pagination.cursor — cadena opaca que se pasa de vuelta como ?cursor= para la siguiente página. null cuando has_more es false.

El parámetro de consulta limit está limitado a 50.

Los cursores son deliberadamente opacos: algunas fuentes usan offsets enteros, otras usan marcas de tiempo, otras usan tokens de página. UnifAPI oculta la variación. No intentes parsear pagination.cursor.

Envelope de error

Todos los errores comparten un único envelope anidado:

{
  "error": {
    "type": "...",
    "message": "...",
    "request_id": "...",
    "issues": [
      /* validation only */
    ]
  }
}

error.type es un vocabulario cerrado (validation_error, not_found, unauthorized, ...). Consulta Errores.

Espacio de trabajo

El límite de facturación y acceso. Las sesiones OAuth de MCP, las API keys, el uso y las facturas viven todas a nivel de espacio de trabajo. Invita a tus compañeros de equipo desde el panel: comparten las mismas claves y el mismo contador de uso.

Límite de datos públicos

UnifAPI sirve datos públicos. OAuth autoriza el acceso MCP de UnifAPI y los créditos del espacio de trabajo; no autoriza cuentas de origen privadas. Si un flujo de trabajo necesita los datos de SaaS privados de un usuario, combina UnifAPI con una plataforma de conectores en lugar de tratar UnifAPI como esa capa de integración OAuth.