{ "openapi": "3.1.0", "info": { "title": "AI Gateway", "version": "main-3de3fce6", "description": "HTTP API for submitting and retrieving asynchronous AI jobs (transcription, translation, video analysis, LLM tasks).\n\n### Async job lifecycle\n\nAll operations follow the same pattern:\n\n1. **Create** — `POST /v1/{resource}` accepts the job and returns **202 Accepted** with a job resource (`status: pending`).\n2. **Process** — the gateway picks up the job, selects a backend provider, and transitions the job to `processing`.\n3. **Complete** — on success the job reaches `completed` and the result is available; on failure it reaches `failed` with an `error` object.\n\nTo retrieve the outcome, either:\n- **Poll** `GET /v1/{resource}/{id}` until `status` is `completed` or `failed`.\n- **Subscribe** by providing `attributes.webhook` in the creation request. The gateway POSTs a lifecycle event payload to that URL on each state transition.\n\nThe result payload is also available separately at `GET /v1/{resource}/{id}/result` once the job is completed.\n\n### Local testing (Swagger UI)\n\n1. Open Swagger UI (default http://localhost:8090/swagger/).\n2. **Authorize** → **oauth2ClientCredentials** → **Authorize** (token URL points to Auth0; audience from `x-oidc-audience` in `/openapi.json`).\n3. Call **POST /v1/transcriptions** (or any other resource), then poll **GET** by job `id`.\n" }, "servers": [ { "url": "https://api.qa.ai.scw.mymedia.services", "description": "API gateway" } ], "security": [ { "oauth2ClientCredentials": [] } ], "tags": [ { "name": "Administration", "description": "Gateway administration — services, providers, tenants, and cross-service job listing" }, { "name": "Policies", "description": "Policies — define provider priority, strategy, and conditions for job routing" }, { "name": "Transcript", "description": "Operations related to converting audio or video content into structured, time-aligned text" }, { "name": "Translation", "description": "Operations related to translating text or document content between languages" }, { "name": "Video Analysis", "description": "Operations related to extracting structured metadata and insights from video content" }, { "name": "LLM", "description": "Operations related to submitting generic language model tasks without coupling to a specific AI vendor or model" }, { "name": "Schemas", "description": "Available schemas" } ], "paths": { "/v1/services": { "get": { "summary": "List available services", "description": "Returns all AI services exposed by the gateway, along with their endpoint paths, job type discriminators, and current operational status. Use this to discover what capabilities the gateway offers and which endpoints to call.\n", "operationId": "listServices", "responses": { "200": { "description": "List of available services", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } } }, "tags": [ "Administration" ] } }, "/v1/providers": { "get": { "summary": "List available providers", "description": "Returns all backend providers configured in the gateway, along with the resource types and features each one supports. Use this to determine which `provider` value to pass when creating a job, and which features are available for a given provider.\n", "operationId": "listProviders", "responses": { "200": { "description": "List of available providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderList" } } } } }, "tags": [ "Administration" ] } }, "/v1/jobs": { "get": { "summary": "List jobs", "description": "Returns a paginated, cross-service list of jobs. When `filter[tenant]` is omitted, the caller's tenant is resolved from their JWT token claim. Super-admins may specify `filter[tenant]` to query jobs for any tenant. Each item contains common job fields only (status, timing, routing, tenant, user) — no service-specific input or result payload. Use `GET /v1/{resource}/{id}/result` to fetch the full result for a completed job.\n", "operationId": "listJobs", "parameters": [ { "name": "filter", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tenant": { "type": "string", "description": "Return only jobs submitted by this tenant slug. When omitted, the caller's tenant is resolved from their JWT token claim. Only super-admins may specify a value; returns 403 otherwise.\n", "example": "acme-corp" }, "user_id": { "type": "string", "description": "Return only jobs submitted by this user or client identifier.", "example": "auth0|64a1b2c3d4e5f6789012345" }, "service": { "type": "string", "description": "Return only jobs belonging to this service. One of `transcriptions`, `translations`, `video-analyses`, `llm-tasks`.\n", "example": "transcriptions" }, "provider": { "type": "string", "description": "Return only jobs processed by this provider.", "example": "eden-ai" }, "status": { "$ref": "#/components/schemas/JobStatus" } } } }, { "name": "page", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-based)." }, "size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of jobs per page." } } } } ], "responses": { "200": { "description": "Paginated list of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "403": { "description": "The caller specified `filter[tenant]` but is not a super-admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Administration" ] } }, "/v1/tenants": { "get": { "summary": "List tenants", "description": "Returns all tenants known to the gateway along with their current service and provider access configuration. Tenants are created and managed externally; this endpoint is read-only.\n", "operationId": "listTenants", "parameters": [ { "name": "page", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-based)." }, "size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of tenants per page." } } } } ], "responses": { "200": { "description": "List of tenants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantList" } } } }, "422": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Administration" ] } }, "/v1/tenants/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Slug identifier of the tenant.", "schema": { "type": "string", "example": "acme-corp" } } ], "get": { "summary": "Get tenant", "description": "Returns the service and provider access configuration for a single tenant.", "operationId": "getTenant", "responses": { "200": { "description": "Tenant access configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tenant" } } } } } }, "404": { "description": "Tenant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Administration" ] }, "patch": { "summary": "Update tenant access", "description": "Enables or disables specific services and providers for a tenant. Only entries included in the request body are changed; all other access settings remain unchanged.\n", "operationId": "updateTenantAccess", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAccessUpdateRequest" } } } }, "responses": { "200": { "description": "Updated tenant access configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tenant" } } } } } }, "404": { "description": "Tenant not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request body or tenant identifier mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Administration" ] } }, "/v1/policies": { "get": { "summary": "List policies", "description": "Returns all policies the caller is authorised to see. When `filter[tenant]` is omitted, the caller's tenant is resolved from their JWT token claim. Super-admins may specify `filter[tenant]` to query policies for any tenant.\n", "operationId": "listPolicies", "parameters": [ { "name": "filter", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tenant": { "type": "string", "description": "Return only policies scoped to this tenant slug. When omitted, the caller's tenant is resolved from their JWT token claim. Only super-admins may specify a value; returns 403 otherwise.\n", "example": "acme-corp" } } } }, { "name": "page", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-based)." }, "size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of policies per page." } } } } ], "responses": { "200": { "description": "List of policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyList" } } } }, "403": { "description": "The caller specified `filter[tenant]` but is not a super-admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Policies" ] }, "post": { "summary": "Create policy", "description": "Creates a new policy. The initial `version` is set to `1`. When `attributes.tenant` is omitted, the caller's tenant is resolved from their JWT token claim. Only super-admins may specify `attributes.tenant`; returns 403 otherwise.\n", "operationId": "createPolicy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCreateRequest" } } } }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Policy" } } } } } }, "403": { "description": "The caller specified `attributes.tenant` but is not a super-admin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (e.g. duplicate provider priorities, unknown provider IDs).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Policies" ] } }, "/v1/policies/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the policy.", "schema": { "type": "string", "format": "uuid", "example": "f4a3b2c1-d5e6-7890-abcd-ef1234567890" } } ], "get": { "summary": "Get policy", "description": "Returns the current version of a policy.", "operationId": "getPolicy", "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Policy" } } } } } }, "404": { "description": "Policy not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Policies" ] }, "put": { "summary": "Replace policy", "description": "Fully replaces a policy. All writable fields must be provided. The `version` is incremented automatically. Jobs that ran under previous versions retain their original routing metadata.\n", "operationId": "replacePolicy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyReplaceRequest" } } } }, "responses": { "200": { "description": "Replaced policy (with incremented version)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Policy" } } } } } }, "404": { "description": "Policy not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (e.g. duplicate provider priorities, unknown provider IDs).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Policies" ] }, "patch": { "summary": "Update policy", "description": "Applies a partial update to a policy. Only the provided fields are changed; omitted fields are left unchanged. The `version` is incremented automatically. Jobs that ran under previous versions retain their original routing metadata.\n", "operationId": "patchPolicy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyPatchRequest" } } } }, "responses": { "200": { "description": "Updated policy (with incremented version)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Policy" } } } } } }, "404": { "description": "Policy not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (e.g. duplicate provider priorities, unknown provider IDs).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Policies" ] }, "delete": { "summary": "Delete policy", "description": "Permanently removes a policy.", "operationId": "deletePolicy", "responses": { "204": { "description": "Policy deleted." }, "404": { "description": "Policy not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Policies" ] } }, "/v1/transcriptions": { "post": { "summary": "Create transcription job", "description": "For **video** input, audio is extracted before transcription begins.\n\nThe `input.url` must be reachable by the gateway and workers (HTTP/HTTPS). In local Compose stacks,\nuse the MinIO sample URL from the request example or your own publicly accessible file.\n", "operationId": "createTranscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRequest" } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "422": { "description": "Validation error — e.g. the selected provider does not support the requested options, or both `provider` and `policy_id` were specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Transcript" ] } }, "/v1/transcriptions/{id}": { "get": { "summary": "Get transcription job", "description": "Use the `id` from the **202** response to **POST /v1/transcriptions**.", "operationId": "getTranscription", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the transcription was created.", "schema": { "type": "string", "format": "uuid", "example": "2f41bc1f-b608-4360-acd9-a26a296fea3c" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Transcript" ] } }, "/v1/transcriptions/{id}/result": { "get": { "summary": "Get transcription result", "description": "Available once `status` is `completed`. Response content type reflects the requested `options.format` (`application/json`, `text/srt`, or `text/vtt`).\n", "operationId": "getTranscriptionResult", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the transcription was created.", "schema": { "type": "string", "format": "uuid", "example": "2f41bc1f-b608-4360-acd9-a26a296fea3c" } } ], "responses": { "200": { "description": "Transcription result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } }, "text/srt": { "schema": { "type": "string" } }, "text/vtt": { "schema": { "type": "string" } } } }, "404": { "description": "Job not found or result not yet available (`RESULT_NOT_READY`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Transcript" ] } }, "/v1/translations": { "post": { "summary": "Create translation job", "operationId": "createTranslation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/translation_CreateRequest" } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/translation_Job" } } } }, "422": { "description": "Validation error — e.g. the selected provider does not support the requested options, or both `provider` and `policy_id` were specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Translation" ] } }, "/v1/translations/{id}": { "get": { "summary": "Get translation job", "description": "Use the `id` from the **202** response to **POST /v1/translations**.", "operationId": "getTranslation", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the translation was created.", "schema": { "type": "string", "format": "uuid", "example": "9a1bc2f3-d405-4678-bcde-f12345678901" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/translation_Job" } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Translation" ] } }, "/v1/translations/{id}/result": { "get": { "summary": "Get translation result", "description": "Available once `status` is `completed`.", "operationId": "getTranslationResult", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the translation was created.", "schema": { "type": "string", "format": "uuid", "example": "9a1bc2f3-d405-4678-bcde-f12345678901" } } ], "responses": { "200": { "description": "Translation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/translation_Result" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Job not found or result not yet available (`RESULT_NOT_READY`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Translation" ] } }, "/v1/video-analyses": { "post": { "summary": "Create video analysis job", "operationId": "createVideoAnalysis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-analysis_CreateRequest" } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-analysis_Job" } } } }, "422": { "description": "Validation error — e.g. the selected provider does not support the requested features, or both `provider` and `policy_id` were specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Video Analysis" ] } }, "/v1/video-analyses/{id}": { "get": { "summary": "Get video analysis job", "description": "Use the `id` from the **202** response to **POST /v1/video-analyses**.", "operationId": "getVideoAnalysis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the video analysis was created.", "schema": { "type": "string", "format": "uuid", "example": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-analysis_Job" } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Video Analysis" ] } }, "/v1/video-analyses/{id}/result": { "get": { "summary": "Get video analysis result", "description": "Available once `status` is `completed`.", "operationId": "getVideoAnalysisResult", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the video analysis was created.", "schema": { "type": "string", "format": "uuid", "example": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345" } } ], "responses": { "200": { "description": "Video analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-analysis_Result" } } } }, "404": { "description": "Job not found or result not yet available (`RESULT_NOT_READY`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Video Analysis" ] } }, "/v1/llm-tasks": { "post": { "summary": "Create LLM task job", "description": "Token usage is returned in `data.meta.system.usage` once the job completes.", "operationId": "createLlmTask", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/llm-task_CreateRequest" } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/llm-task_Job" } } } }, "422": { "description": "Validation error — e.g. the selected provider does not support the requested options, or both `provider` and `policy_id` were specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "LLM" ] } }, "/v1/llm-tasks/{id}": { "get": { "summary": "Get LLM task job", "description": "Use the `id` from the **202** response to **POST /v1/llm-tasks**.", "operationId": "getLlmTask", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the LLM task was created.", "schema": { "type": "string", "format": "uuid", "example": "c3d2e1f0-a4b5-6789-cdef-012345678901" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/llm-task_Job" } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "LLM" ] } }, "/v1/llm-tasks/{id}/result": { "get": { "summary": "Get LLM task result", "description": "Available once `status` is `completed`.", "operationId": "getLlmTaskResult", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job UUID returned when the LLM task was created.", "schema": { "type": "string", "format": "uuid", "example": "c3d2e1f0-a4b5-6789-cdef-012345678901" } } ], "responses": { "200": { "description": "LLM task result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/llm-task_Result" } } } }, "404": { "description": "Job not found or result not yet available (`RESULT_NOT_READY`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "LLM" ] } } }, "webhooks": { "transcription": { "post": { "summary": "Transcription job lifecycle event", "operationId": "transcriptionWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully" } }, "tags": [ "Transcript" ] } }, "translation": { "post": { "summary": "Translation job lifecycle event", "operationId": "translationWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/translation_WebhookPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully" } }, "tags": [ "Translation" ] } }, "video-analysis": { "post": { "summary": "Video analysis job lifecycle event", "operationId": "videoAnalysisWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/video-analysis_WebhookPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully" } }, "tags": [ "Video Analysis" ] } }, "llm-task": { "post": { "summary": "LLM task job lifecycle event", "operationId": "llmTaskWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/llm-task_WebhookPayload" } } } }, "responses": { "200": { "description": "Webhook received successfully" } }, "tags": [ "LLM" ] } } }, "components": { "securitySchemes": { "oauth2ClientCredentials": { "type": "oauth2", "description": "OIDC client credentials (machine-to-machine). Swagger obtains tokens from Auth0; runtime `tokenUrl` and `x-oidc-audience` are set in `/openapi.json`.", "x-oidc-audience": "https://api.ai-gateway.bce.lu", "flows": { "clientCredentials": { "tokenUrl": "https://qa-maas.eu.auth0.com/oauth/token", "scopes": {} } }, "x-oidc-issuer": "https://qa-maas.eu.auth0.com/" } }, "schemas": { "ServiceAttributes": { "type": "object", "description": "Details of an AI Gateway service.", "properties": { "name": { "type": "string", "description": "Human-readable name of the service.", "example": "Transcription" }, "description": { "type": "string", "description": "Brief description of what the service does.", "example": "Converts audio or video content into structured, time-aligned text." }, "endpoint": { "type": "string", "description": "Base API endpoint path for this service.", "example": "/v1/transcriptions" }, "job_type": { "type": "string", "description": "Resource type discriminator used in the `data.type` field when creating jobs for this service.", "example": "transcription-job" }, "status": { "type": "string", "description": "Current operational status of the service.", "enum": [ "active", "deprecated", "disabled" ], "example": "active" } } }, "Service": { "type": "object", "description": "An AI service exposed by the gateway.", "properties": { "id": { "type": "string", "description": "Unique identifier for the service. Matches the URL path segment used for job creation.", "example": "transcriptions" }, "type": { "type": "string", "enum": [ "service" ], "description": "Resource type identifier. Always `service`.", "example": "service" }, "attributes": { "$ref": "#/components/schemas/ServiceAttributes" } } }, "ServiceList": { "type": "object", "description": "List of AI services exposed by the gateway.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "ProviderStatus": { "type": "string", "description": "Current operational status of a provider or one of its capabilities. `active`: fully operational. `degraded`: operational with reduced performance or reliability. `disabled`: not available for new jobs.\n", "enum": [ "active", "degraded", "disabled" ], "example": "active" }, "Feature": { "type": "string", "description": "A specific transcription capability that may or may not be supported by a given provider. `language_detection`: automatically detect the source language without explicit specification. `diarization`: identify and label distinct speakers in the transcript. `timestamps`: produce time-aligned transcript segments.\n", "enum": [ "language_detection", "diarization", "timestamps" ] }, "ProviderLimits": { "type": "object", "description": "Usage limits for a provider capability.", "properties": { "requests_per_minute": { "type": "integer", "description": "Maximum number of requests allowed per minute.", "example": 60 }, "requests_per_day": { "type": "integer", "description": "Maximum number of requests allowed per day.", "example": 10000 }, "max_file_size_mb": { "type": "integer", "description": "Maximum input file size in megabytes. Applies to file-based capabilities.", "example": 500 }, "max_duration_seconds": { "type": "integer", "description": "Maximum media duration in seconds. Applies to audio/video capabilities.", "example": 7200 } } }, "ProviderPricing": { "type": "object", "description": "Pricing information for a provider capability.", "properties": { "unit": { "type": "string", "description": "Billing unit for this capability.", "enum": [ "per_minute", "per_character", "per_page", "per_request", "per_token" ], "example": "per_minute" }, "amount": { "type": "number", "format": "double", "description": "Cost per unit.", "example": 0.024 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" } } }, "TranscriptionCapabilities": { "type": "object", "description": "Transcription capabilities offered by this provider.", "properties": { "features": { "type": "array", "description": "Subset of transcription features this provider can handle.", "items": { "$ref": "#/components/schemas/Feature" }, "example": [ "language_detection", "diarization", "timestamps" ] }, "languages": { "type": "array", "description": "BCP 47 language codes supported for transcription input. Absence of this field means the provider accepts all languages.\n", "items": { "type": "string" }, "example": [ "en", "fr", "de", "es", "pt", "nl", "it", "ja", "zh" ] }, "limits": { "$ref": "#/components/schemas/ProviderLimits" }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" }, "status": { "$ref": "#/components/schemas/ProviderStatus" } } }, "translation_Feature": { "type": "string", "description": "A specific translation capability that may or may not be supported by a given provider. `language_detection`: automatically detect the source language without explicit specification. `formality`: control the formality level (formal, informal) of the translated output.\n", "enum": [ "language_detection", "formality" ] }, "TranslationCapabilities": { "type": "object", "description": "Translation capabilities offered by this provider.", "properties": { "features": { "type": "array", "description": "Subset of translation features this provider can handle.", "items": { "$ref": "#/components/schemas/translation_Feature" }, "example": [ "language_detection", "formality" ] }, "source_languages": { "type": "array", "description": "BCP 47 language codes accepted as translation input.", "items": { "type": "string" }, "example": [ "en", "fr", "de", "es", "pt", "nl", "it" ] }, "target_languages": { "type": "array", "description": "BCP 47 language codes that can be produced as translation output.", "items": { "type": "string" }, "example": [ "fr", "de", "es", "pt", "nl", "it", "ja", "zh" ] }, "limits": { "$ref": "#/components/schemas/ProviderLimits" }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" }, "status": { "$ref": "#/components/schemas/ProviderStatus" } } }, "video-analysis_Feature": { "type": "string", "description": "A specific analysis capability to apply to the video. `labels`: detect objects, scenes, and actions throughout the video. `scenes`: detect scene and shot boundaries. `faces`: detect and track faces across frames. `speech_to_text`: convert speech to text, with speaker identification. `ocr`: extract on-screen text from video frames. `content_moderation`: flag explicit or inappropriate content. `sentiment`: analyse the overall tone and emotional valence. `topics`: extract key topics and keywords from audio and visual content. `brands`: detect brand logos and visual trademarks. `summary`: generate a natural-language description of the video content.\n", "enum": [ "labels", "scenes", "faces", "speech_to_text", "ocr", "content_moderation", "sentiment", "topics", "brands", "summary" ] }, "VideoAnalysisCapabilities": { "type": "object", "description": "Video analysis capabilities offered by this provider.", "properties": { "features": { "type": "array", "description": "Subset of video analysis features this provider can handle.", "items": { "$ref": "#/components/schemas/video-analysis_Feature" }, "example": [ "labels", "scenes", "faces", "speech_to_text", "ocr", "content_moderation", "sentiment", "topics", "brands", "summary" ] }, "limits": { "$ref": "#/components/schemas/ProviderLimits" }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" }, "status": { "$ref": "#/components/schemas/ProviderStatus" } } }, "LlmTaskCapabilities": { "type": "object", "description": "LLM task capabilities offered by this provider.", "properties": { "models": { "type": "array", "description": "LLM model identifiers available through this provider.", "items": { "type": "string" }, "example": [ "gpt-4o", "gpt-4o-mini" ] }, "limits": { "$ref": "#/components/schemas/ProviderLimits" }, "pricing": { "$ref": "#/components/schemas/ProviderPricing" }, "status": { "$ref": "#/components/schemas/ProviderStatus" } } }, "ProviderAttributes": { "type": "object", "description": "Capabilities of a provider across all supported services.", "properties": { "name": { "type": "string", "description": "Human-readable name of the provider.", "example": "TwelveLabs" }, "status": { "$ref": "#/components/schemas/ProviderStatus" }, "services": { "type": "object", "description": "Capabilities offered by this provider per service. Only services supported by this provider appear in this object.\n", "properties": { "transcriptions": { "$ref": "#/components/schemas/TranscriptionCapabilities" }, "translations": { "$ref": "#/components/schemas/TranslationCapabilities" }, "video-analyses": { "$ref": "#/components/schemas/VideoAnalysisCapabilities" }, "llm-tasks": { "$ref": "#/components/schemas/LlmTaskCapabilities" } } } } }, "ProviderList": { "type": "object", "description": "List of available backend providers.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the provider.", "example": "twelvelabs" }, "type": { "type": "string", "enum": [ "provider" ], "example": "provider" }, "attributes": { "$ref": "#/components/schemas/ProviderAttributes" } } } } } }, "JobStatus": { "type": "string", "description": "Current lifecycle state of the job. `pending`: accepted, waiting to be picked up. `processing`: actively being worked on. `completed`: finished successfully. `failed`: encountered an unrecoverable error.\n", "enum": [ "pending", "processing", "completed", "failed" ], "example": "processing" }, "Provider": { "type": "string", "description": "Identifier of the backend provider to use for processing this job. When omitted, the gateway selects the most appropriate provider automatically based on the requested features and availability. Use `GET /v1/providers` to list available providers and their supported features.\n", "example": "twelvelabs" }, "Error": { "type": "object", "description": "Details of a job failure. Only present when `status` is `failed`.", "properties": { "code": { "type": "string", "description": "Machine-readable error identifier.", "example": "AUDIO_UNREADABLE" }, "message": { "type": "string", "description": "Human-readable explanation of the error.", "example": "Could not extract audio from the provided file." } } }, "RoutingInfo": { "type": "object", "readOnly": true, "description": "Snapshot of the routing decision made for this job. Present once the job leaves the `pending` state and included in all lifecycle webhook payloads. `provider_id`, `reason`, and `attempt` are always present; `policy_id` and `policy_version` are only present when `reason` is `policy_rule`.\n", "required": [ "provider_id", "reason", "attempt" ], "properties": { "provider_id": { "type": "string", "description": "Identifier of the provider selected to process this job.", "example": "eden-ai" }, "reason": { "type": "string", "description": "Why this provider was chosen. `explicit_choice`: the client specified this provider in the request. `policy_rule`: a routing policy matched and designated this provider. `failover`: the initially selected provider failed; this is a retry attempt on a different provider. `default`: no specific rule applied; the gateway selected the best available provider.\n", "enum": [ "explicit_choice", "policy_rule", "failover", "default" ], "example": "policy_rule" }, "policy_id": { "type": "string", "format": "uuid", "description": "ID of the policy that determined provider selection. Present only when `reason` is `policy_rule`.\n", "example": "f4a3b2c1-d5e6-7890-abcd-ef1234567890" }, "policy_version": { "type": "integer", "minimum": 1, "description": "Version of the policy that was active at routing time. Present only when `reason` is `policy_rule`. Matches `attributes.version` on the `Policy` resource at the time of the routing decision, enabling audit reconstruction if the policy is later updated.\n", "example": 3 }, "policy_source": { "type": "string", "description": "How the routing policy was resolved when `reason` is `policy_rule`. `explicit_id`: the client specified `policy_id` in the request. `tenant_default`: the tenant's configured default policy was used. `tenant_latest`: the most recently updated tenant-scoped policy was used. `global_latest`: the most recently updated gateway-wide policy was used. `none`: no policy applied (e.g. `explicit_choice` or `default` routing).\n", "enum": [ "explicit_id", "tenant_default", "tenant_latest", "global_latest", "none" ], "example": "tenant_default" }, "attempt": { "type": "integer", "description": "Which attempt this is (1-based). Values greater than 1 indicate a failover retry.", "minimum": 1, "example": 1 } } }, "Attributes": { "type": "object", "description": "Base attributes shared by all asynchronous job types.", "properties": { "tenant": { "readOnly": true, "type": "string", "description": "Slug of the tenant that submitted the job. Derived from the authentication token.", "example": "acme-corp" }, "user_id": { "readOnly": true, "type": "string", "description": "Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.", "example": "auth0|64a1b2c3d4e5f6789012345" }, "provider": { "readOnly": true, "$ref": "#/components/schemas/Provider" }, "status": { "readOnly": true, "$ref": "#/components/schemas/JobStatus" }, "progress": { "readOnly": true, "type": "integer", "minimum": 0, "maximum": 100, "description": "Processing progress as a percentage. Only meaningful while status is `processing`.", "example": 72 }, "error": { "readOnly": true, "$ref": "#/components/schemas/Error" }, "routing": { "readOnly": true, "$ref": "#/components/schemas/RoutingInfo" }, "created_at": { "readOnly": true, "type": "string", "format": "date-time", "description": "When the job was created.", "example": "2024-03-15T10:00:00Z" }, "processed_at": { "readOnly": true, "type": "string", "format": "date-time", "description": "When the job transitioned from `pending` to `processing`. Subtract from `created_at` to get queue wait time.", "example": "2024-03-15T10:00:05Z" }, "completed_at": { "readOnly": true, "type": "string", "format": "date-time", "description": "When the job reached a terminal state (`completed` or `failed`). Subtract from `processed_at` to get processing duration.", "example": "2024-03-15T10:02:30Z" } } }, "ListMeta": { "type": "object", "description": "Metadata included in all JSON:API collection responses.", "required": [ "total" ], "properties": { "total": { "type": "integer", "description": "Total number of items matching the current filters.", "example": 142 }, "page_count": { "type": "integer", "description": "Total number of pages for the current page size.", "example": 8 }, "page": { "type": "integer", "description": "Current page number (1-based).", "example": 2 }, "per_page": { "type": "integer", "description": "Number of items per page used for this response.", "example": 20 } } }, "PaginationLinks": { "type": "object", "description": "JSON:API pagination links included in all collection responses.", "required": [ "self", "first", "prev", "next", "last" ], "properties": { "self": { "type": "string", "format": "uri", "description": "The current page." }, "first": { "type": "string", "format": "uri", "description": "The first page." }, "prev": { "type": [ "string", "null" ], "format": "uri", "description": "The previous page. Null when on the first page." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "The next page. Null when on the last page." }, "last": { "type": "string", "format": "uri", "description": "The last page." } } }, "JobList": { "type": "object", "description": "JSON:API collection response for jobs. Returns common job fields only — no service-specific input or result payload. Use `GET /v1/{resource}/{id}/result` for full results.\n", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A job summary entry.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the job.", "example": "2f41bc1f-b608-4360-acd9-a26a296fea3c" }, "type": { "type": "string", "description": "Resource type discriminator identifying the service this job belongs to. One of `transcription-job`, `translation-job`, `video-analysis-job`, `llm-task-job`.\n", "example": "transcription-job" }, "attributes": { "$ref": "#/components/schemas/Attributes" } } } }, "meta": { "$ref": "#/components/schemas/ListMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "ErrorResponse": { "type": "object", "description": "Standard error response envelope.", "properties": { "error": { "$ref": "#/components/schemas/Error" } } }, "TenantServiceConfig": { "type": "object", "description": "Access configuration for a single service within a tenant.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether this service is available to the tenant.", "example": true } } }, "TenantProviderConfig": { "type": "object", "description": "Access configuration for a single provider within a tenant.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether this provider is available to the tenant.", "example": true } } }, "TenantAttributes": { "type": "object", "description": "Service and provider access configuration for a tenant.", "properties": { "services": { "type": "object", "description": "Per-service access configuration for this tenant. Keys are service IDs (e.g. `transcriptions`). Services absent from this map inherit the default access policy.\n", "additionalProperties": { "$ref": "#/components/schemas/TenantServiceConfig" }, "example": { "transcriptions": { "enabled": true }, "translations": { "enabled": false } } }, "providers": { "type": "object", "description": "Per-provider access configuration for this tenant. Keys are provider IDs (e.g. `eden-ai`). Providers absent from this map inherit the default access policy.\n", "additionalProperties": { "$ref": "#/components/schemas/TenantProviderConfig" }, "example": { "eden-ai": { "enabled": true }, "twelvelabs": { "enabled": false } } } } }, "Tenant": { "type": "object", "description": "A tenant identified by a unique slug, with its service and provider access configuration.", "properties": { "id": { "type": "string", "description": "Unique slug identifier for the tenant.", "example": "acme-corp" }, "type": { "type": "string", "enum": [ "tenant" ], "description": "Resource type identifier. Always `tenant`.", "example": "tenant" }, "attributes": { "$ref": "#/components/schemas/TenantAttributes" } } }, "TenantList": { "type": "object", "description": "Paginated list of tenants.", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } }, "meta": { "$ref": "#/components/schemas/ListMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "TenantAccessUpdateRequest": { "type": "object", "description": "Request body to update a tenant's service and provider access configuration. Only the fields provided are changed; omitted entries are left unchanged.\n", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "Slug of the tenant being updated. Must match the `{slug}` path parameter.", "example": "acme-corp" }, "type": { "type": "string", "enum": [ "tenant" ], "example": "tenant" }, "attributes": { "type": "object", "description": "Partial access configuration to apply.", "properties": { "services": { "type": "object", "description": "Service access overrides. Each key is a service ID; the value sets `enabled` for that service. Services not included in the map are unchanged.\n", "additionalProperties": { "$ref": "#/components/schemas/TenantServiceConfig" }, "example": { "translations": { "enabled": true } } }, "providers": { "type": "object", "description": "Provider access overrides. Each key is a provider ID; the value sets `enabled` for that provider. Providers not included in the map are unchanged.\n", "additionalProperties": { "$ref": "#/components/schemas/TenantProviderConfig" }, "example": { "twelvelabs": { "enabled": true } } } } } } } } }, "PolicyProvider": { "type": "object", "description": "A provider entry within a routing policy.", "required": [ "provider_id", "priority" ], "properties": { "provider_id": { "type": "string", "description": "Identifier of the provider.", "example": "eden-ai" }, "priority": { "type": "integer", "description": "Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.\n", "minimum": 1, "example": 1 }, "weight": { "type": "integer", "description": "Relative weight for load distribution. Used when `routing_strategy` is `round_robin`; ignored otherwise.\n", "minimum": 1, "example": 3 }, "conditions": { "type": "object", "description": "Optional eligibility conditions for this provider entry. All specified conditions must be satisfied for this provider to be considered. When absent, the provider is always eligible.\n", "properties": { "max_file_size_mb": { "type": "integer", "description": "Only route to this provider when the input file is smaller than this threshold (in MB).", "example": 200 }, "languages": { "type": "array", "description": "Only route to this provider when the job targets one of these BCP 47 language codes.", "items": { "type": "string" }, "example": [ "en", "fr", "de" ] } } } } }, "PolicyAttributes": { "type": "object", "description": "Configuration and metadata for a routing policy.", "properties": { "tenant": { "readOnly": true, "type": [ "string", "null" ], "description": "Slug of the tenant this policy is scoped to. `null` means the policy is a gateway-wide default, visible to super-admins only.\n", "example": "acme-corp" }, "name": { "type": "string", "description": "Human-readable name of the policy.", "example": "Cost-optimised production" }, "description": { "type": "string", "description": "Describes the intent or scope of this policy.", "example": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives." }, "version": { "readOnly": true, "type": "integer", "description": "Monotonically increasing version number. Automatically incremented each time the policy is updated. Jobs record the `policy_id` and version that was active at routing time.\n", "minimum": 1, "example": 3 }, "routing_strategy": { "type": "string", "description": "Primary criterion used to rank and select providers when multiple are eligible. `latency`: prefer the provider with the lowest expected response time. `quality`: prefer the provider with the highest quality score for the requested capability. `price`: prefer the cheapest provider. `round_robin`: distribute jobs evenly across all eligible providers, weighted by `providers[].weight`.\n", "enum": [ "latency", "quality", "price", "round_robin" ], "example": "price" }, "services": { "type": "array", "description": "Service IDs this policy applies to (e.g. `transcriptions`, `translations`). An empty array or absent field means the policy applies to all services.\n", "items": { "type": "string" }, "example": [ "transcriptions", "translations" ] }, "providers": { "type": "array", "description": "Ordered list of providers eligible under this policy. The gateway evaluates providers in ascending `priority` order and selects the first one that satisfies all conditions and availability checks.\n", "items": { "$ref": "#/components/schemas/PolicyProvider" } }, "created_at": { "readOnly": true, "type": "string", "format": "date-time", "description": "When the policy was first created.", "example": "2024-03-15T10:00:00Z" }, "updated_at": { "readOnly": true, "type": "string", "format": "date-time", "description": "When the policy was last updated (i.e. when the current version was created).", "example": "2024-03-16T09:45:00Z" } } }, "Policy": { "type": "object", "description": "A routing policy defining how the gateway selects providers for jobs. Each update creates a new immutable version; the latest version is always active.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the policy.", "example": "f4a3b2c1-d5e6-7890-abcd-ef1234567890" }, "type": { "type": "string", "enum": [ "policy" ], "description": "Resource type identifier. Always `policy`.", "example": "policy" }, "attributes": { "$ref": "#/components/schemas/PolicyAttributes" } } }, "PolicyList": { "type": "object", "description": "Paginated list of routing policies.", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "meta": { "$ref": "#/components/schemas/ListMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "PolicyCreateAttributes": { "type": "object", "required": [ "name", "routing_strategy", "providers" ], "properties": { "tenant": { "type": "string", "description": "Slug of the tenant to scope this policy to. When omitted, the caller's tenant is resolved from their JWT token claim. Only super-admins may specify this field; returns 403 otherwise.\n", "example": "acme-corp" }, "name": { "type": "string", "description": "Human-readable name of the policy.", "example": "Cost-optimised production" }, "description": { "type": "string", "description": "Describes the intent or scope of this policy." }, "routing_strategy": { "type": "string", "enum": [ "latency", "quality", "price", "round_robin" ], "example": "price" }, "services": { "type": "array", "description": "Service IDs this policy applies to. Omit to apply to all services.", "items": { "type": "string" } }, "providers": { "type": "array", "description": "Ordered provider list. Must contain at least one entry.", "minItems": 1, "items": { "$ref": "#/components/schemas/PolicyProvider" } } } }, "PolicyCreateRequest": { "type": "object", "description": "Request body to create a new routing policy.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "policy" ], "example": "policy" }, "attributes": { "$ref": "#/components/schemas/PolicyCreateAttributes" } } } } }, "PolicyReplaceAttributes": { "type": "object", "required": [ "name", "routing_strategy", "providers" ], "properties": { "name": { "type": "string", "description": "Human-readable name of the policy.", "example": "Cost-optimised production" }, "description": { "type": "string", "description": "Describes the intent or scope of this policy." }, "routing_strategy": { "type": "string", "enum": [ "latency", "quality", "price", "round_robin" ], "example": "price" }, "services": { "type": "array", "description": "Service IDs this policy applies to. Omit or pass empty array to apply to all services.", "items": { "type": "string" } }, "providers": { "type": "array", "description": "Full ordered provider list. Must contain at least one entry.", "minItems": 1, "items": { "$ref": "#/components/schemas/PolicyProvider" } } } }, "PolicyReplaceRequest": { "type": "object", "description": "Request body for a full policy replacement (`PUT`). All writable fields must be provided; the `version` is incremented automatically.\n", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of the policy being replaced. Must match the `{id}` path parameter.", "example": "f4a3b2c1-d5e6-7890-abcd-ef1234567890" }, "type": { "type": "string", "enum": [ "policy" ], "example": "policy" }, "attributes": { "$ref": "#/components/schemas/PolicyReplaceAttributes" } } } } }, "PolicyPatchAttributes": { "type": "object", "description": "Fields to update. All fields are optional; only provided fields are changed.", "properties": { "name": { "type": "string", "description": "New name for the policy." }, "description": { "type": "string", "description": "New description for the policy." }, "routing_strategy": { "type": "string", "enum": [ "latency", "quality", "price", "round_robin" ] }, "services": { "type": "array", "description": "Replaces the full list of applicable services.", "items": { "type": "string" } }, "providers": { "type": "array", "description": "Replaces the full ordered provider list. Must contain at least one entry if provided.", "minItems": 1, "items": { "$ref": "#/components/schemas/PolicyProvider" } } } }, "PolicyPatchRequest": { "type": "object", "description": "Request body for a partial policy update (`PATCH`). Only provided fields are changed; omitted fields are left unchanged. A successful patch creates a new version; the `version` field in the response is incremented.\n", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of the policy being updated. Must match the `{id}` path parameter.", "example": "f4a3b2c1-d5e6-7890-abcd-ef1234567890" }, "type": { "type": "string", "enum": [ "policy" ], "example": "policy" }, "attributes": { "$ref": "#/components/schemas/PolicyPatchAttributes" } } } } }, "Input": { "type": "object", "description": "Identifies the media file to transcribe. The URL must be reachable from the gateway and worker services (no authentication headers are forwarded).\n", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "description": "Media kind. `video` — audio is extracted from the container, then transcribed (two-step pipeline). `audio` — the file is transcribed directly.\n", "enum": [ "video", "audio" ], "example": "video" }, "url": { "type": "string", "format": "uri", "description": "HTTP or HTTPS URL of the source file (e.g. MP4, WAV, MP3). Must be publicly accessible or reachable on the deployment network (e.g. MinIO in local Docker Compose).\n", "example": "http://minio:9000/ai-gateway/samples/speech_sample.mp4" }, "audio_track": { "type": "integer", "description": "Zero-based index of the audio track to transcribe when `type` is `video`. Omit to use the first audio track. Ignored for `type` `audio`.\n", "example": 0 } } }, "Options": { "type": "object", "description": "Optional settings for the transcription engine and result shape. Provider capabilities vary; unsupported combinations may return **422**. Check **GET /v1/providers** for supported features.\n", "properties": { "language": { "type": "string", "description": "BCP 47 language code of the speech in the source media (e.g. `en`, `en-US`, `fr`, `de`). Two-letter codes are normalized where applicable (`en` → `en-US`). Use `auto` to request automatic language detection when the selected provider supports it. The default Eden AI Google engine does **not** auto-detect; specify a language explicitly or rely on the deployment default (typically `en-US`) when this field is omitted.\n", "example": "en" }, "timestamps": { "type": "boolean", "description": "When `true`, the result includes a `segments` array with `start`, `end`, and `text` for each utterance. When `false` or omitted, the backend may return plain text only (provider-dependent).\n", "default": true, "example": true }, "format": { "type": "string", "description": "How the transcript is returned in `attributes.result` and **GET /v1/transcriptions/{id}/result**. `json` — structured object with `segments` (recommended for APIs). `srt` / `vtt` — SubRip or WebVTT subtitle text; a `download_url` may be provided when the provider exports a file.\n", "enum": [ "srt", "vtt", "json" ], "example": "json" }, "diarization": { "type": "boolean", "description": "When `true`, requests speaker diarization (who spoke when). Support depends on the provider; see `diarization` under transcription features in **GET /v1/providers**.\n", "default": false, "example": false }, "priority": { "type": "string", "description": "Relative queue priority for the job. `high` jobs are scheduled before `standard` and `low` when the platform is under load. Does not change transcription quality.\n", "enum": [ "low", "standard", "high" ], "default": "standard", "example": "standard" } } }, "Webhook": { "writeOnly": true, "type": "object", "description": "Destination configuration for job lifecycle notifications.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The endpoint the gateway will POST event payloads to.", "example": "https://webhook.site/64be6fc3-7869-48c1-85bc-a28a6c756ab7" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional HTTP headers included in every webhook request. Typically used for authentication." } } }, "PolicyId": { "type": "string", "format": "uuid", "description": "UUID of the routing policy to apply to this job. When omitted, the gateway uses the policy assigned to the caller's tenant, or the gateway-wide default. Cannot be combined with an explicit `provider`; returns 422 if both are specified.\n", "example": "f4a3b2c1-d5e6-7890-abcd-ef1234567890" }, "AttributesCreate": { "type": "object", "description": "Parameters that control what is transcribed and how. Only `input` is required; configure `options`, `webhook`, and `provider` as needed.\n", "required": [ "input" ], "properties": { "input": { "description": "Source audio or video file to transcribe.", "$ref": "#/components/schemas/Input" }, "options": { "description": "Optional transcription settings (language, output format, timestamps, diarization, priority). See the **Options** schema for field-level details.\n", "$ref": "#/components/schemas/Options" }, "webhook": { "description": "Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (`transcription.progress`, `transcription.completed`, `transcription.failed`).\n", "$ref": "#/components/schemas/Webhook" }, "provider": { "description": "Backend provider id for this job (e.g. `eden-ai`). When omitted, the gateway picks a provider that supports the requested options. List providers and features with **GET /v1/providers**.\n", "$ref": "#/components/schemas/Provider" }, "policy_id": { "$ref": "#/components/schemas/PolicyId" } } }, "Meta": { "type": "object", "description": "Metadata envelope shared between client and system.", "properties": { "client": { "type": "object", "additionalProperties": true, "description": "Arbitrary key-value data provided by the client. Returned unchanged in all responses." }, "system": { "readOnly": true, "type": "object", "additionalProperties": true, "description": "Internal metadata added by the gateway. Not exposed unless explicitly required.", "example": { "region": "eu-west-1", "worker_id": "wk_789" } } } }, "CreateRequest": { "type": "object", "description": "Request body for **POST /v1/transcriptions**. Wraps job parameters in a JSON:API-style `data` object. The gateway enqueues the job and returns immediately; transcription runs asynchronously.\n", "required": [ "data" ], "example": { "data": { "type": "transcription-job", "attributes": { "input": { "type": "video", "url": "http://minio:9000/ai-gateway/samples/speech_sample.mp4" }, "options": { "language": "en", "timestamps": true, "format": "json", "diarization": false, "priority": "standard" }, "webhook": { "url": "https://webhook.site/64be6fc3-7869-48c1-85bc-a28a6c756ab7" } } } }, "properties": { "data": { "type": "object", "description": "JSON:API-style resource envelope. Must include `type` and `attributes`; `meta` is optional.\n", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "Resource type discriminator. Must be exactly `transcription-job` for this endpoint.\n", "example": "transcription-job" }, "attributes": { "$ref": "#/components/schemas/AttributesCreate" }, "meta": { "description": "Optional client metadata (`meta.client`). Stored with the job and returned unchanged in GET responses and webhook payloads. Not used for routing or processing.\n", "$ref": "#/components/schemas/Meta" } } } } }, "Segment": { "type": "object", "description": "A single time-aligned segment of the transcript.", "properties": { "start": { "type": "number", "description": "Start time of the segment in seconds.", "example": 12.5 }, "end": { "type": "number", "description": "End time of the segment in seconds.", "example": 15.8 }, "text": { "type": "string", "description": "Transcribed text for this time range.", "example": "Welcome to today's interview." } } }, "Result": { "type": "object", "description": "Output of a completed transcription job.", "properties": { "format": { "type": "string", "enum": [ "srt", "vtt", "json" ], "description": "Format of the transcription result, matching the requested output format.", "example": "srt" }, "duration": { "type": "number", "description": "Total duration of the media file in seconds.", "example": 183.4 }, "language": { "type": "string", "description": "BCP 47 language code of the transcribed audio, as detected or specified.", "example": "en" }, "download_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the full transcription file. Valid for a limited time.", "example": "https://storage.example.com/results/2f41bc1f-b608-4360-acd9-a26a296fea3c.srt" }, "segments": { "type": "array", "description": "Time-aligned transcript segments. Present when `timestamps` was enabled.", "items": { "$ref": "#/components/schemas/Segment" } } } }, "transcription_Attributes": { "description": "Full attributes of a transcription job, combining input, job state, and result.", "allOf": [ { "$ref": "#/components/schemas/Attributes" }, { "$ref": "#/components/schemas/AttributesCreate" }, { "type": "object", "properties": { "result": { "readOnly": true, "description": "Transcription output. Populated once status is `completed`.", "$ref": "#/components/schemas/Result" } } } ] }, "Job": { "type": "object", "description": "A transcription job resource, including its current status and result when available.", "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transcription job.", "example": "2f41bc1f-b608-4360-acd9-a26a296fea3c" }, "type": { "type": "string", "enum": [ "transcription-job" ], "description": "Resource type identifier. Always `transcription-job`.", "example": "transcription-job" }, "attributes": { "$ref": "#/components/schemas/transcription_Attributes" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "translation_Input": { "type": "object", "description": "Source content to translate.", "required": [ "type", "target_language" ], "properties": { "type": { "type": "string", "description": "Type of the source content.", "enum": [ "text", "document" ], "example": "text" }, "content": { "type": "string", "description": "The text content to translate. Required when `type` is `text`.", "example": "Hello, how are you today?" }, "url": { "type": "string", "format": "uri", "description": "Publicly accessible URL of the document to translate. Required when `type` is `document`.", "example": "https://cdn.example.com/documents/report.pdf" }, "target_language": { "type": "string", "description": "BCP 47 language code of the target language.", "example": "fr" } } }, "translation_Options": { "type": "object", "description": "Optional settings controlling translation behaviour.", "properties": { "source_language": { "type": "string", "description": "BCP 47 language code of the source content. Use `auto` to detect the language automatically.", "example": "auto" }, "formality": { "type": "string", "description": "Formality level of the translated output.", "enum": [ "default", "formal", "informal" ], "example": "formal" }, "priority": { "type": "string", "description": "Processing priority. Higher priority jobs are picked up sooner.", "enum": [ "low", "standard", "high" ], "example": "standard" } } }, "translation_AttributesCreate": { "type": "object", "description": "Input fields required to create a translation job.", "required": [ "input" ], "properties": { "input": { "$ref": "#/components/schemas/translation_Input" }, "options": { "$ref": "#/components/schemas/translation_Options" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "provider": { "$ref": "#/components/schemas/Provider" }, "policy_id": { "$ref": "#/components/schemas/PolicyId" } } }, "translation_CreateRequest": { "type": "object", "description": "Request body to create a new translation job.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "Resource type identifier. Must be `translation-job`.", "example": "translation-job" }, "attributes": { "$ref": "#/components/schemas/translation_AttributesCreate" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "translation_Result": { "type": "object", "description": "Output of a completed translation job.", "properties": { "source_language": { "type": "string", "description": "BCP 47 language code of the source content, as detected or specified.", "example": "en" }, "target_language": { "type": "string", "description": "BCP 47 language code of the translated output.", "example": "fr" }, "content": { "type": "string", "description": "Translated text content. Present when input `type` is `text`.", "example": "Bonjour, comment allez-vous aujourd'hui ?" }, "download_url": { "type": "string", "format": "uri", "description": "Pre-signed URL to download the translated file. Valid for a limited time. Present when input `type` is `document`.", "example": "https://storage.example.com/results/9a1bc2f3-d405-4678-bcde-f12345678901.pdf" }, "character_count": { "type": "integer", "description": "Number of characters in the source content.", "example": 1250 } } }, "translation_Attributes": { "description": "Full attributes of a translation job, combining input, job state, and result.", "allOf": [ { "$ref": "#/components/schemas/Attributes" }, { "$ref": "#/components/schemas/translation_AttributesCreate" }, { "type": "object", "properties": { "result": { "readOnly": true, "description": "Translation output. Populated once status is `completed`.", "$ref": "#/components/schemas/translation_Result" } } } ] }, "translation_Job": { "type": "object", "description": "A translation job resource, including its current status and result when available.", "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the translation job.", "example": "9a1bc2f3-d405-4678-bcde-f12345678901" }, "type": { "type": "string", "enum": [ "translation-job" ], "description": "Resource type identifier. Always `translation-job`.", "example": "translation-job" }, "attributes": { "$ref": "#/components/schemas/translation_Attributes" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "video-analysis_Input": { "type": "object", "description": "Source video and the list of analysis features to run.", "required": [ "url", "features" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Publicly accessible URL of the video file.", "example": "https://cdn.example.com/videos/conference-talk.mp4" }, "features": { "type": "array", "description": "One or more analysis capabilities to apply. At least one feature must be specified.", "minItems": 1, "items": { "$ref": "#/components/schemas/video-analysis_Feature" }, "example": [ "labels", "scenes", "speech_to_text", "summary" ] }, "audio_track": { "type": "integer", "description": "Index of the audio track to use for speech-related features. Defaults to the first track when omitted.", "example": 0 } } }, "video-analysis_Options": { "type": "object", "description": "Optional settings controlling analysis behaviour.", "properties": { "language": { "type": "string", "description": "BCP 47 language code for speech and text features. Use `auto` to detect the language automatically.", "example": "auto" }, "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum confidence score (0–1) for a detection to be included in the result. Defaults to 0.5.", "example": 0.7 }, "priority": { "type": "string", "description": "Processing priority. Higher priority jobs are picked up sooner.", "enum": [ "low", "standard", "high" ], "example": "standard" } } }, "video-analysis_AttributesCreate": { "type": "object", "description": "Input fields required to create a video analysis job.", "required": [ "input" ], "properties": { "input": { "$ref": "#/components/schemas/video-analysis_Input" }, "options": { "$ref": "#/components/schemas/video-analysis_Options" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "provider": { "$ref": "#/components/schemas/Provider" }, "policy_id": { "$ref": "#/components/schemas/PolicyId" } } }, "video-analysis_CreateRequest": { "type": "object", "description": "Request body to create a new video analysis job.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "Resource type identifier. Must be `video-analysis-job`.", "example": "video-analysis-job" }, "attributes": { "$ref": "#/components/schemas/video-analysis_AttributesCreate" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "VideoMetadata": { "type": "object", "description": "Technical properties of the processed video file.", "properties": { "duration": { "type": "number", "description": "Total duration of the video in seconds.", "example": 3742.5 }, "width": { "type": "integer", "description": "Video width in pixels.", "example": 1920 }, "height": { "type": "integer", "description": "Video height in pixels.", "example": 1080 }, "frame_rate": { "type": "number", "description": "Frames per second of the video.", "example": 29.97 }, "format": { "type": "string", "description": "Container format of the video file.", "example": "mp4" }, "codec": { "type": "string", "description": "Video codec used for encoding.", "example": "h264" } } }, "TimedInstance": { "type": "object", "description": "A time range in which a detection is active, with an optional per-occurrence confidence score.", "properties": { "start": { "type": "number", "description": "Start time of the occurrence in seconds.", "example": 12.5 }, "end": { "type": "number", "description": "End time of the occurrence in seconds.", "example": 15.8 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score for this specific occurrence.", "example": 0.91 } } }, "LabelDetection": { "type": "object", "description": "A detected object, scene, or action with its temporal occurrences.", "properties": { "name": { "type": "string", "description": "Human-readable name of the detected label.", "example": "Conference room" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall confidence score for this label across the video.", "example": 0.94 }, "instances": { "type": "array", "description": "Time ranges in which this label was detected.", "items": { "$ref": "#/components/schemas/TimedInstance" } } } }, "SceneDetection": { "type": "object", "description": "A distinct scene or shot within the video.", "properties": { "index": { "type": "integer", "description": "Zero-based position of this scene in the video.", "example": 3 }, "start": { "type": "number", "description": "Start time of the scene in seconds.", "example": 42 }, "end": { "type": "number", "description": "End time of the scene in seconds.", "example": 78.5 } } }, "FaceDetection": { "type": "object", "description": "A face detected and tracked across the video.", "properties": { "track_id": { "type": "integer", "description": "Integer identifier grouping all appearances of the same face within this video.", "example": 1 }, "fingerprint": { "type": "string", "description": "Base64-encoded face embedding vector produced by the underlying model. When present, fingerprints from different videos can be compared for similarity to determine whether the same person appears across videos. Fingerprints are only comparable when produced by the same backend model — cross-model comparison is not meaningful. Not all backends populate this field.\n", "example": "7hGkL2mXqP9nRsT4vWzA..." }, "instances": { "type": "array", "description": "Time ranges in which this face is visible.", "items": { "$ref": "#/components/schemas/TimedInstance" } } } }, "TranscriptSegment": { "type": "object", "description": "A speech-to-text segment with optional speaker attribution.", "properties": { "start": { "type": "number", "description": "Start time of the segment in seconds.", "example": 12.5 }, "end": { "type": "number", "description": "End time of the segment in seconds.", "example": 15.8 }, "text": { "type": "string", "description": "Transcribed speech for this time range.", "example": "Welcome to today's panel discussion on AI safety." }, "speaker_id": { "type": "integer", "description": "Integer identifier grouping segments from the same speaker.", "example": 0 }, "language": { "type": "string", "description": "BCP 47 language code detected for this segment.", "example": "en" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score for this transcript segment.", "example": 0.97 } } }, "OcrText": { "type": "object", "description": "On-screen text detected within video frames.", "properties": { "text": { "type": "string", "description": "The detected text string.", "example": "Q3 Revenue: $4.2M" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score for this text detection.", "example": 0.91 }, "language": { "type": "string", "description": "BCP 47 language code of the detected text.", "example": "en" }, "instances": { "type": "array", "description": "Time ranges in which this text is visible on screen.", "items": { "$ref": "#/components/schemas/TimedInstance" } } } }, "ModerationSignal": { "type": "object", "description": "A specific content moderation signal with its temporal occurrences.", "properties": { "label": { "type": "string", "description": "Machine-readable label identifying the type of flagged content.", "enum": [ "explicit_nudity", "suggestive", "violence", "visually_disturbing", "hate_symbols", "tobacco", "alcohol", "gambling" ], "example": "violence" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall confidence score for this signal across the video.", "example": 0.82 }, "instances": { "type": "array", "description": "Time ranges in which this signal was detected.", "items": { "$ref": "#/components/schemas/TimedInstance" } } } }, "ContentModeration": { "type": "object", "description": "Content moderation signals detected in the video.", "properties": { "is_safe": { "type": "boolean", "description": "Whether the video passed moderation at the requested confidence threshold.", "example": true }, "signals": { "type": "array", "description": "Individual moderation signals detected above the confidence threshold.", "items": { "$ref": "#/components/schemas/ModerationSignal" } } } }, "SentimentInstance": { "type": "object", "description": "Sentiment detected within a specific time range.", "properties": { "start": { "type": "number", "description": "Start time of the segment in seconds.", "example": 0 }, "end": { "type": "number", "description": "End time of the segment in seconds.", "example": 45 }, "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ], "description": "Sentiment label for this time range.", "example": "positive" }, "score": { "type": "number", "minimum": -1, "maximum": 1, "description": "Sentiment score for this time range.", "example": 0.71 } } }, "Sentiment": { "type": "object", "description": "Overall sentiment and tone of the video.", "properties": { "overall": { "type": "string", "description": "Dominant sentiment across the entire video.", "enum": [ "positive", "neutral", "negative" ], "example": "positive" }, "score": { "type": "number", "minimum": -1, "maximum": 1, "description": "Aggregate sentiment score from -1 (most negative) to 1 (most positive).", "example": 0.62 }, "instances": { "type": "array", "description": "Sentiment variations across the video timeline.", "items": { "$ref": "#/components/schemas/SentimentInstance" } } } }, "Topic": { "type": "object", "description": "A topic or keyword extracted from the video content.", "properties": { "name": { "type": "string", "description": "Topic or keyword name.", "example": "artificial intelligence" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score for this topic.", "example": 0.95 }, "instances": { "type": "array", "description": "Time ranges in which this topic is relevant.", "items": { "$ref": "#/components/schemas/TimedInstance" } } } }, "BrandDetection": { "type": "object", "description": "A detected brand logo or visual trademark.", "properties": { "name": { "type": "string", "description": "Name of the detected brand.", "example": "Acme Corp" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall confidence score for this brand detection.", "example": 0.88 }, "instances": { "type": "array", "description": "Time ranges in which this brand is visible on screen.", "items": { "$ref": "#/components/schemas/TimedInstance" } } } }, "video-analysis_Result": { "type": "object", "description": "Output of a completed video analysis job. Only fields corresponding to the requested features are populated.", "properties": { "video_metadata": { "readOnly": true, "$ref": "#/components/schemas/VideoMetadata" }, "labels": { "readOnly": true, "type": "array", "description": "Detected objects, scenes, and actions. Present when `labels` was requested.", "items": { "$ref": "#/components/schemas/LabelDetection" } }, "scenes": { "readOnly": true, "type": "array", "description": "Scene and shot boundaries. Present when `scenes` was requested.", "items": { "$ref": "#/components/schemas/SceneDetection" } }, "faces": { "readOnly": true, "type": "array", "description": "Faces detected and tracked across the video. Present when `faces` was requested.", "items": { "$ref": "#/components/schemas/FaceDetection" } }, "speech_to_text": { "readOnly": true, "type": "array", "description": "Speech-to-text segments with speaker identification. Present when `speech_to_text` was requested.", "items": { "$ref": "#/components/schemas/TranscriptSegment" } }, "ocr": { "readOnly": true, "type": "array", "description": "On-screen text extracted from video frames. Present when `ocr` was requested.", "items": { "$ref": "#/components/schemas/OcrText" } }, "content_moderation": { "readOnly": true, "description": "Content moderation signals. Present when `content_moderation` was requested.", "$ref": "#/components/schemas/ContentModeration" }, "sentiment": { "readOnly": true, "description": "Overall tone and sentiment of the video. Present when `sentiment` was requested.", "$ref": "#/components/schemas/Sentiment" }, "topics": { "readOnly": true, "type": "array", "description": "Key topics and keywords extracted from the video. Present when `topics` was requested.", "items": { "$ref": "#/components/schemas/Topic" } }, "brands": { "readOnly": true, "type": "array", "description": "Detected brand logos and visual trademarks. Present when `brands` was requested.", "items": { "$ref": "#/components/schemas/BrandDetection" } }, "summary": { "readOnly": true, "type": "string", "description": "Natural-language description of the video content. Present when `summary` was requested.", "example": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n" } } }, "video-analysis_Attributes": { "description": "Full attributes of a video analysis job, combining input, job state, and result.", "allOf": [ { "$ref": "#/components/schemas/Attributes" }, { "$ref": "#/components/schemas/video-analysis_AttributesCreate" }, { "type": "object", "properties": { "result": { "readOnly": true, "description": "Video analysis output. Populated once status is `completed`.", "$ref": "#/components/schemas/video-analysis_Result" } } } ] }, "video-analysis_Job": { "type": "object", "description": "A video analysis job resource, including its current status and result when available.", "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the video analysis job.", "example": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345" }, "type": { "type": "string", "enum": [ "video-analysis-job" ], "description": "Resource type identifier. Always `video-analysis-job`.", "example": "video-analysis-job" }, "attributes": { "$ref": "#/components/schemas/video-analysis_Attributes" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "llm-task_Input": { "description": "The task instruction and the content to process.", "allOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of the source content supplied for the task.", "enum": [ "text", "document" ], "example": "text" } } }, { "oneOf": [ { "title": "Text input", "required": [ "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "description": "Inline text content for the model to process.", "example": "Artificial intelligence is transforming industries at an unprecedented pace..." } } }, { "title": "Document input", "required": [ "url" ], "properties": { "type": { "const": "document" }, "url": { "type": "string", "format": "uri", "description": "Publicly accessible URL of the document for the model to process.", "example": "https://cdn.example.com/documents/report.pdf" } } } ] }, { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Instruction describing the task the model should perform on the provided content.", "example": "Summarise the following article in three bullet points." }, "system_prompt": { "type": "string", "description": "Optional system-level instruction that shapes the model's behaviour and tone throughout the task. Provided in addition to — and processed before — the user prompt.\n", "example": "You are a helpful assistant. Always respond in plain language suitable for a general audience." } } } ] }, "llm-task_Options": { "type": "object", "description": "Generation settings for the LLM task.", "properties": { "creativity": { "type": "string", "description": "Controls how exploratory or deterministic the model's output should be. `precise`: strongly favour the most likely continuation; best for factual or structured tasks. `balanced`: moderate exploration; suitable for most general-purpose tasks. `creative`: high exploration; best for brainstorming, ideation, or open-ended generation.\n", "enum": [ "precise", "balanced", "creative" ], "example": "balanced" } } }, "llm-task_AttributesCreate": { "type": "object", "description": "Input fields required to create an LLM task job.", "required": [ "input" ], "properties": { "input": { "$ref": "#/components/schemas/llm-task_Input" }, "options": { "$ref": "#/components/schemas/llm-task_Options" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "provider": { "$ref": "#/components/schemas/Provider" }, "policy_id": { "$ref": "#/components/schemas/PolicyId" } } }, "llm-task_CreateRequest": { "type": "object", "description": "Request body to create a new LLM task job.", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "Resource type identifier. Must be `llm-task-job`.", "example": "llm-task-job" }, "attributes": { "$ref": "#/components/schemas/llm-task_AttributesCreate" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "llm-task_Result": { "type": "object", "description": "Output of a completed LLM task job.", "properties": { "content": { "type": "string", "description": "The model-generated text produced in response to the prompt.", "example": "• AI adoption accelerated sharply in 2024.\n• Regulatory frameworks remain fragmented across jurisdictions.\n• Open-source models narrowed the gap with proprietary systems." }, "finish_reason": { "type": "string", "description": "Reason the model stopped generating. `completed`: the model finished naturally. `max_tokens`: the output was truncated at the provider's or policy's token limit.\n", "enum": [ "completed", "max_tokens" ], "example": "completed" } } }, "llm-task_Attributes": { "description": "Full attributes of an LLM task job, combining input, job state, and result.", "allOf": [ { "$ref": "#/components/schemas/Attributes" }, { "$ref": "#/components/schemas/llm-task_AttributesCreate" }, { "type": "object", "properties": { "result": { "readOnly": true, "description": "LLM task output. Populated once status is `completed`.", "$ref": "#/components/schemas/llm-task_Result" } } } ] }, "Usage": { "type": "object", "description": "Token consumption for the job, useful for cost attribution and quota tracking.", "readOnly": true, "properties": { "input_tokens": { "type": "integer", "description": "Number of tokens in the combined system prompt and user prompt.", "example": 312 }, "output_tokens": { "type": "integer", "description": "Number of tokens in the model-generated output.", "example": 87 } } }, "llm-task_Meta": { "description": "Metadata envelope for an LLM task job. `meta.client` is echoed back unchanged from the request. `meta.system` is populated by the gateway and includes token usage once the job completes.\n", "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "system": { "readOnly": true, "type": "object", "properties": { "usage": { "$ref": "#/components/schemas/Usage" } } } } } ] }, "llm-task_Job": { "type": "object", "description": "An LLM task job resource, including its current status and result when available.", "properties": { "data": { "type": "object", "description": "JSON:API-style data envelope.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the LLM task job.", "example": "c3d2e1f0-a4b5-6789-cdef-012345678901" }, "type": { "type": "string", "enum": [ "llm-task-job" ], "description": "Resource type identifier. Always `llm-task-job`.", "example": "llm-task-job" }, "attributes": { "$ref": "#/components/schemas/llm-task_Attributes" }, "meta": { "$ref": "#/components/schemas/llm-task_Meta" } } } } }, "WebhookPayload": { "description": "Envelope delivered to your webhook URL on every transcription job lifecycle event. The `event` field identifies the transition that occurred; `data` contains the full job resource at the time the event was triggered.\n", "allOf": [ { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The lifecycle event that triggered this notification. `transcription.progress`: the job is processing; `data.attributes.progress` is updated. `transcription.completed`: the job finished successfully; `data.attributes.result` is populated. `transcription.failed`: the job encountered an unrecoverable error; `data.attributes.error` is populated.\n", "enum": [ "transcription.progress", "transcription.completed", "transcription.failed" ], "example": "transcription.completed" } } }, { "$ref": "#/components/schemas/Job" } ] }, "translation_WebhookPayload": { "description": "Envelope delivered to your webhook URL on every translation job lifecycle event. The `event` field identifies the transition that occurred; `data` contains the full job resource at the time the event was triggered.\n", "allOf": [ { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The lifecycle event that triggered this notification. `translation.progress`: the job is processing; `data.attributes.progress` is updated. `translation.completed`: the job finished successfully; `data.attributes.result` is populated. `translation.failed`: the job encountered an unrecoverable error; `data.attributes.error` is populated.\n", "enum": [ "translation.progress", "translation.completed", "translation.failed" ], "example": "translation.completed" } } }, { "$ref": "#/components/schemas/translation_Job" } ] }, "video-analysis_WebhookPayload": { "description": "Envelope delivered to your webhook URL on every video analysis job lifecycle event. The `event` field identifies the transition that occurred; `data` contains the full job resource at the time the event was triggered.\n", "allOf": [ { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The lifecycle event that triggered this notification. `video-analysis.progress`: the job is processing; `data.attributes.progress` is updated. `video-analysis.completed`: the job finished successfully; `data.attributes.result` is populated. `video-analysis.failed`: the job encountered an unrecoverable error; `data.attributes.error` is populated.\n", "enum": [ "video-analysis.progress", "video-analysis.completed", "video-analysis.failed" ], "example": "video-analysis.completed" } } }, { "$ref": "#/components/schemas/video-analysis_Job" } ] }, "llm-task_WebhookPayload": { "description": "Envelope delivered to your webhook URL on every LLM task job lifecycle event. The `event` field identifies the transition that occurred; `data` contains the full job resource at the time the event was triggered.\n", "allOf": [ { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The lifecycle event that triggered this notification. `llm-task.completed`: the job finished successfully; `data.attributes.result` is populated. `llm-task.failed`: the job encountered an unrecoverable error; `data.attributes.error` is populated.\n", "enum": [ "llm-task.completed", "llm-task.failed" ], "example": "llm-task.completed" } } }, { "$ref": "#/components/schemas/llm-task_Job" } ] } } } }