iblai-api-external-service-proxy

iblai-api-external-service-proxy

A service-agnostic gateway for calling third-party AI providers (ElevenLabs, HeyGen, …) through ibl.ai instead of hitting them directly. One request shape fronts every provider; the provider's API key is stored server-side per org and injected upstream, so the client never holds it. Work in two phases: discover a service's endpoints, then invoke one. Configure the provider keys with /iblai-api-integration; get IBLAI_ORG/IBLAI_API_KEY from /iblai-api-login.

Auth & conventions

• Header: Authorization: Api-Token $IBLAI_API_KEY on every request. The token must belong to a platform admin — all three endpoints are platform-admin gated (a non-admin token → 403; no token → 401).
• Base: https://api.iblai.app/dm/api/ai-proxy/orgs/{org} — {org} = $IBLAI_ORG (a.k.a. platform_key). App segment is ai-proxy; backend routes are bare /api/..., the gateway prepends /dm.
• Run /iblai-api-login first to populate $IBLAI_ORG / $IBLAI_API_KEY.
• Provider credentials are configured out-of-band by a platform admin (see Notes), not through this API. Resolution follows each service's credential_policy.
• Confirm with the user first for any billable or destructive action — invoking a tts, generate-*, translate-*, dubbing, or delete action hits a paid third-party API or removes provider-side data.

Concepts

Everything here is read off service discovery (below) — the proxy resolves {action} against a per-service endpoint registry, it is not a separate route.

• The invoke envelope — the JSON body you POST to invoke an action. All keys are optional and forwarded upstream:

  {
    "body": {},         // JSON payload sent as the provider's request body (its own schema)
    "query": {},        // upstream query-string params
    "headers": {},      // extra upstream headers
    "path_params": {}   // fills {placeholders} in the endpoint's path_template
  }
  

  There is no files key. For multipart/binary endpoints, send a real multipart request instead: put body/query/path_params as JSON-string form fields and attach the file(s) as their own form fields — the server reads request.FILES and forwards them upstream.
• request_mode (per endpoint): raw (no body — GET/DELETE), json (JSON body), multipart (file upload + fields), binary (raw file bytes as the body, e.g. HeyGen upload-asset).
• response_mode (per endpoint): json (parse JSON), passthrough (raw upstream bytes forwarded verbatim with the upstream Content-Type — audio/video; write to a file, don't JSON-parse), stream (chunked/SSE). There is no separate binary response mode — binary payloads come back as passthrough.
• path_template — the upstream path with {placeholders}; every placeholder must be supplied in path_params (e.g. /v1/text-to-speech/{voice_id} needs path_params.voice_id). Omit one → 400.
• callback_mode: poll — async actions (HeyGen generate-*, translate-video; ElevenLabs create-dubbing) return a job/video id; poll the matching status action until it completes.