API docs by Redocly

AI Gateway (dev)

Download OpenAPI specification:Download

HTTP API for submitting and retrieving asynchronous AI jobs (transcription, translation, video analysis, LLM tasks).

Async job lifecycle

All operations follow the same pattern:

  1. Create — POST /v1/{resource} accepts the job and returns 202 Accepted with a job resource (status: pending).
  2. Process — the gateway picks up the job, selects a backend provider, and transitions the job to processing.
  3. Complete — on success the job reaches completed and the result is available; on failure it reaches failed with an error object.

To retrieve the outcome, either:

  • Poll GET /v1/{resource}/{id} until status is completed or failed.
  • Subscribe by providing attributes.webhook in the creation request. The gateway POSTs a lifecycle event payload to that URL on each state transition.

The result payload is also available separately at GET /v1/{resource}/{id}/result once the job is completed.

Local testing (Swagger UI)

  1. Open Swagger UI (default http://localhost:8090/swagger/).
  2. Authorize → oauth2ClientCredentials → Authorize (token URL points to Auth0; audience from x-oidc-audience in /openapi.json).
  3. Call POST /v1/transcriptions (or any other resource), then poll GET by job id.

Administration

Gateway administration — services, providers, tenants, and cross-service job listing

List available services

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.

Authorizations:
oauth2ClientCredentials

Responses

Response Schema: application/json
Array of objects (Service)
Array
id
string

Unique identifier for the service. Matches the URL path segment used for job creation.

type
string
Value: "service"

Resource type identifier. Always service.

object (ServiceAttributes)

Details of an AI Gateway service.

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "transcriptions",
      • "type": "service",
      • "attributes": {
        • "name": "Transcription",
        • "description": "Converts audio or video content into structured, time-aligned text.",
        • "endpoint": "/v1/transcriptions",
        • "job_type": "transcription-job",
        • "status": "active"
        }
      }
    ]
}

List available providers

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.

Authorizations:
oauth2ClientCredentials

Responses

Response Schema: application/json
Array of objects
Array
id
string

Unique identifier for the provider.

type
string
Value: "provider"
object (ProviderAttributes)

Capabilities of a provider across all supported services.

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "twelvelabs",
      • "type": "provider",
      • "attributes": {
        • "name": "TwelveLabs",
        • "status": "active",
        • "services": {
          • "transcriptions": {
            },
          • "translations": {
            },
          • "video-analyses": {
            },
          • "llm-tasks": {
            }
          }
        }
      }
    ]
}

List jobs

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.

Authorizations:
oauth2ClientCredentials
query Parameters
object
object

Responses

Response Schema: application/json
required
Array of objects
Array
id
string <uuid>

Unique identifier for the job.

type
string

Resource type discriminator identifying the service this job belongs to. One of transcription-job, translation-job, video-analysis-job, llm-task-job.

object (Attributes)

Base attributes shared by all asynchronous job types.

required
object (ListMeta)

Metadata included in all JSON:API collection responses.

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

required
object (PaginationLinks)

JSON:API pagination links included in all collection responses.

self
required
string <uri>

The current page.

first
required
string <uri>

The first page.

prev
required
string or null <uri>

The previous page. Null when on the first page.

next
required
string or null <uri>

The next page. Null when on the last page.

last
required
string <uri>

The last page.

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
      • "type": "transcription-job",
      • "attributes": {
        • "tenant": "acme-corp",
        • "user_id": "auth0|64a1b2c3d4e5f6789012345",
        • "provider": "twelvelabs",
        • "status": "processing",
        • "progress": 72,
        • "error": {
          • "code": "AUDIO_UNREADABLE",
          • "message": "Could not extract audio from the provided file."
          },
        • "routing": {
          • "provider_id": "eden-ai",
          • "reason": "policy_rule",
          • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
          • "policy_version": 3,
          • "policy_source": "tenant_default",
          • "attempt": 1
          },
        • "created_at": "2024-03-15T10:00:00Z",
        • "processed_at": "2024-03-15T10:00:05Z",
        • "completed_at": "2024-03-15T10:02:30Z"
        }
      }
    ],
  • "meta": {
    • "total": 142,
    • "page_count": 8,
    • "page": 2,
    • "per_page": 20
    },
  • "links": {}
}

List tenants

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.

Authorizations:
oauth2ClientCredentials
query Parameters
object

Responses

Response Schema: application/json
required
Array of objects (Tenant)
Array
id
string

Unique slug identifier for the tenant.

type
string
Value: "tenant"

Resource type identifier. Always tenant.

object (TenantAttributes)

Service and provider access configuration for a tenant.

required
object (ListMeta)

Metadata included in all JSON:API collection responses.

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

required
object (PaginationLinks)

JSON:API pagination links included in all collection responses.

self
required
string <uri>

The current page.

first
required
string <uri>

The first page.

prev
required
string or null <uri>

The previous page. Null when on the first page.

next
required
string or null <uri>

The next page. Null when on the last page.

last
required
string <uri>

The last page.

Response samples

Content type
application/json
{}

Get tenant

Returns the service and provider access configuration for a single tenant.

Authorizations:
oauth2ClientCredentials
path Parameters
slug
required
string
Example: acme-corp

Slug identifier of the tenant.

Responses

Response Schema: application/json
object (Tenant)

A tenant identified by a unique slug, with its service and provider access configuration.

id
string

Unique slug identifier for the tenant.

type
string
Value: "tenant"

Resource type identifier. Always tenant.

object (TenantAttributes)

Service and provider access configuration for a tenant.

object

Per-service access configuration for this tenant. Keys are service IDs (e.g. transcriptions). Services absent from this map inherit the default access policy.

object

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.

Response samples

Content type
application/json
{
  • "data": {
    • "id": "acme-corp",
    • "type": "tenant",
    • "attributes": {
      • "services": {
        • "transcriptions": {
          • "enabled": true
          },
        • "translations": {
          • "enabled": false
          }
        },
      • "providers": {
        • "eden-ai": {
          • "enabled": true
          },
        • "twelvelabs": {
          • "enabled": false
          }
        }
      }
    }
}

Update tenant access

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.

Authorizations:
oauth2ClientCredentials
path Parameters
slug
required
string
Example: acme-corp

Slug identifier of the tenant.

Request Body schema: application/json
required
required
object
id
required
string

Slug of the tenant being updated. Must match the {slug} path parameter.

type
required
string
Value: "tenant"
required
object

Partial access configuration to apply.

object

Service access overrides. Each key is a service ID; the value sets enabled for that service. Services not included in the map are unchanged.

object

Provider access overrides. Each key is a provider ID; the value sets enabled for that provider. Providers not included in the map are unchanged.

Responses

Response Schema: application/json
object (Tenant)

A tenant identified by a unique slug, with its service and provider access configuration.

id
string

Unique slug identifier for the tenant.

type
string
Value: "tenant"

Resource type identifier. Always tenant.

object (TenantAttributes)

Service and provider access configuration for a tenant.

object

Per-service access configuration for this tenant. Keys are service IDs (e.g. transcriptions). Services absent from this map inherit the default access policy.

object

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.

Request samples

Content type
application/json
{
  • "data": {
    • "id": "acme-corp",
    • "type": "tenant",
    • "attributes": {
      • "services": {
        • "translations": {
          • "enabled": true
          }
        },
      • "providers": {
        • "twelvelabs": {
          • "enabled": true
          }
        }
      }
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "acme-corp",
    • "type": "tenant",
    • "attributes": {
      • "services": {
        • "transcriptions": {
          • "enabled": true
          },
        • "translations": {
          • "enabled": false
          }
        },
      • "providers": {
        • "eden-ai": {
          • "enabled": true
          },
        • "twelvelabs": {
          • "enabled": false
          }
        }
      }
    }
}

Policies

Policies — define provider priority, strategy, and conditions for job routing

List policies

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.

Authorizations:
oauth2ClientCredentials
query Parameters
object
object

Responses

Response Schema: application/json
required
Array of objects (Policy)
Array
id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

required
object (ListMeta)

Metadata included in all JSON:API collection responses.

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

required
object (PaginationLinks)

JSON:API pagination links included in all collection responses.

self
required
string <uri>

The current page.

first
required
string <uri>

The first page.

prev
required
string or null <uri>

The previous page. Null when on the first page.

next
required
string or null <uri>

The next page. Null when on the last page.

last
required
string <uri>

The last page.

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "type": "policy",
      • "attributes": {
        • "tenant": "acme-corp",
        • "name": "Cost-optimised production",
        • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
        • "version": 3,
        • "routing_strategy": "price",
        • "services": [
          • "transcriptions",
          • "translations"
          ],
        • "providers": [
          • {
            }
          ],
        • "created_at": "2024-03-15T10:00:00Z",
        • "updated_at": "2024-03-16T09:45:00Z"
        }
      }
    ],
  • "meta": {
    • "total": 142,
    • "page_count": 8,
    • "page": 2,
    • "per_page": 20
    },
  • "links": {}
}

Create policy

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.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
required
object
type
required
string
Value: "policy"
required
object (PolicyCreateAttributes)
tenant
string

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.

name
required
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

routing_strategy
required
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Service IDs this policy applies to. Omit to apply to all services.

required
Array of objects (PolicyProvider) non-empty

Ordered provider list. Must contain at least one entry.

Responses

Response Schema: application/json
object (Policy)

A routing policy defining how the gateway selects providers for jobs. Each update creates a new immutable version; the latest version is always active.

id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

tenant
string or null

Slug of the tenant this policy is scoped to. null means the policy is a gateway-wide default, visible to super-admins only.

name
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

version
integer >= 1

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.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"

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.

services
Array of strings

Service IDs this policy applies to (e.g. transcriptions, translations). An empty array or absent field means the policy applies to all services.

Array of objects (PolicyProvider)

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.

created_at
string <date-time>

When the policy was first created.

updated_at
string <date-time>

When the policy was last updated (i.e. when the current version was created).

Request samples

Content type
application/json
{
  • "data": {
    • "type": "policy",
    • "attributes": {
      • "tenant": "acme-corp",
      • "name": "Cost-optimised production",
      • "description": "string",
      • "routing_strategy": "price",
      • "services": [
        • "string"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ]
      }
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "tenant": "acme-corp",
      • "name": "Cost-optimised production",
      • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
      • "version": 3,
      • "routing_strategy": "price",
      • "services": [
        • "transcriptions",
        • "translations"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ],
      • "created_at": "2024-03-15T10:00:00Z",
      • "updated_at": "2024-03-16T09:45:00Z"
      }
    }
}

Get policy

Returns the current version of a policy.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: f4a3b2c1-d5e6-7890-abcd-ef1234567890

UUID of the policy.

Responses

Response Schema: application/json
object (Policy)

A routing policy defining how the gateway selects providers for jobs. Each update creates a new immutable version; the latest version is always active.

id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

tenant
string or null

Slug of the tenant this policy is scoped to. null means the policy is a gateway-wide default, visible to super-admins only.

name
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

version
integer >= 1

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.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"

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.

services
Array of strings

Service IDs this policy applies to (e.g. transcriptions, translations). An empty array or absent field means the policy applies to all services.

Array of objects (PolicyProvider)

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.

created_at
string <date-time>

When the policy was first created.

updated_at
string <date-time>

When the policy was last updated (i.e. when the current version was created).

Response samples

Content type
application/json
{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "tenant": "acme-corp",
      • "name": "Cost-optimised production",
      • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
      • "version": 3,
      • "routing_strategy": "price",
      • "services": [
        • "transcriptions",
        • "translations"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ],
      • "created_at": "2024-03-15T10:00:00Z",
      • "updated_at": "2024-03-16T09:45:00Z"
      }
    }
}

Replace policy

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.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: f4a3b2c1-d5e6-7890-abcd-ef1234567890

UUID of the policy.

Request Body schema: application/json
required
required
object
id
required
string <uuid>

UUID of the policy being replaced. Must match the {id} path parameter.

type
required
string
Value: "policy"
required
object (PolicyReplaceAttributes)
name
required
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

routing_strategy
required
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Service IDs this policy applies to. Omit or pass empty array to apply to all services.

required
Array of objects (PolicyProvider) non-empty

Full ordered provider list. Must contain at least one entry.

Responses

Response Schema: application/json
object (Policy)

A routing policy defining how the gateway selects providers for jobs. Each update creates a new immutable version; the latest version is always active.

id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

tenant
string or null

Slug of the tenant this policy is scoped to. null means the policy is a gateway-wide default, visible to super-admins only.

name
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

version
integer >= 1

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.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"

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.

services
Array of strings

Service IDs this policy applies to (e.g. transcriptions, translations). An empty array or absent field means the policy applies to all services.

Array of objects (PolicyProvider)

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.

created_at
string <date-time>

When the policy was first created.

updated_at
string <date-time>

When the policy was last updated (i.e. when the current version was created).

Request samples

Content type
application/json
{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "name": "Cost-optimised production",
      • "description": "string",
      • "routing_strategy": "price",
      • "services": [
        • "string"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ]
      }
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "tenant": "acme-corp",
      • "name": "Cost-optimised production",
      • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
      • "version": 3,
      • "routing_strategy": "price",
      • "services": [
        • "transcriptions",
        • "translations"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ],
      • "created_at": "2024-03-15T10:00:00Z",
      • "updated_at": "2024-03-16T09:45:00Z"
      }
    }
}

Update policy

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.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: f4a3b2c1-d5e6-7890-abcd-ef1234567890

UUID of the policy.

Request Body schema: application/json
required
required
object
id
required
string <uuid>

UUID of the policy being updated. Must match the {id} path parameter.

type
required
string
Value: "policy"
required
object (PolicyPatchAttributes)

Fields to update. All fields are optional; only provided fields are changed.

name
string

New name for the policy.

description
string

New description for the policy.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Replaces the full list of applicable services.

Array of objects (PolicyProvider) non-empty

Replaces the full ordered provider list. Must contain at least one entry if provided.

Responses

Response Schema: application/json
object (Policy)

A routing policy defining how the gateway selects providers for jobs. Each update creates a new immutable version; the latest version is always active.

id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

tenant
string or null

Slug of the tenant this policy is scoped to. null means the policy is a gateway-wide default, visible to super-admins only.

name
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

version
integer >= 1

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.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"

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.

services
Array of strings

Service IDs this policy applies to (e.g. transcriptions, translations). An empty array or absent field means the policy applies to all services.

Array of objects (PolicyProvider)

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.

created_at
string <date-time>

When the policy was first created.

updated_at
string <date-time>

When the policy was last updated (i.e. when the current version was created).

Request samples

Content type
application/json
{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "name": "string",
      • "description": "string",
      • "routing_strategy": "latency",
      • "services": [
        • "string"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ]
      }
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "tenant": "acme-corp",
      • "name": "Cost-optimised production",
      • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
      • "version": 3,
      • "routing_strategy": "price",
      • "services": [
        • "transcriptions",
        • "translations"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ],
      • "created_at": "2024-03-15T10:00:00Z",
      • "updated_at": "2024-03-16T09:45:00Z"
      }
    }
}

Delete policy

Permanently removes a policy.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: f4a3b2c1-d5e6-7890-abcd-ef1234567890

UUID of the policy.

Responses

Response samples

Content type
application/json
{
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    }
}

Transcript

Operations related to converting audio or video content into structured, time-aligned text

Transcription job lifecycle event Webhook

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
event
required
string
Enum: "transcription.progress" "transcription.completed" "transcription.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the transcription job.

type
string
Value: "transcription-job"

Resource type identifier. Always transcription-job.

object (transcription_Attributes)

Full attributes of a transcription job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (Input)

Source audio or video file to transcribe.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

policy_id
string <uuid> (PolicyId)

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.

object (Result)

Transcription output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Responses

Request samples

Content type
application/json
{
  • "event": "transcription.completed",
  • "data": {
    • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
    • "type": "transcription-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "en",
        • "timestamps": true,
        • "format": "json",
        • "diarization": false,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Create transcription job

For video input, audio is extracted before transcription begins.

The input.url must be reachable by the gateway and workers (HTTP/HTTPS). In local Compose stacks, use the MinIO sample URL from the request example or your own publicly accessible file.

Usage is returned in data.attributes.result.usage once the job completes, but only when data.attributes.options.include_usage is true.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
required
object

JSON:API-style resource envelope. Must include type and attributes; meta is optional.

type
required
string

Resource type discriminator. Must be exactly transcription-job for this endpoint.

required
object (AttributesCreate)

Parameters that control what is transcribed and how. Only input is required; configure options, webhook, and provider as needed.

required
object (Input)

Source audio or video file to transcribe.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

object (Webhook)

Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (transcription.progress, transcription.completed, transcription.failed).

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Optional client metadata (meta.client). Stored with the job and returned unchanged in GET responses and webhook payloads. Not used for routing or processing.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
    • "type": "transcription-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "en",
        • "timestamps": true,
        • "format": "json",
        • "diarization": false,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get transcription job

Use the id from the 202 response to POST /v1/transcriptions.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: 2f41bc1f-b608-4360-acd9-a26a296fea3c

Job UUID returned when the transcription was created.

Responses

Response Schema: application/json
object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the transcription job.

type
string
Value: "transcription-job"

Resource type identifier. Always transcription-job.

object (transcription_Attributes)

Full attributes of a transcription job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (Input)

Source audio or video file to transcribe.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

policy_id
string <uuid> (PolicyId)

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.

object (Result)

Transcription output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Response samples

Content type
application/json
{
  • "data": {
    • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
    • "type": "transcription-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "en",
        • "timestamps": true,
        • "format": "json",
        • "diarization": false,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get transcription result

Available once status is completed. Response content type reflects the requested options.format (application/json, text/srt, or text/vtt).

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: 2f41bc1f-b608-4360-acd9-a26a296fea3c

Job UUID returned when the transcription was created.

Responses

Response Schema:
format
string
Enum: "srt" "vtt" "json"

Format of the transcription result, matching the requested output format.

duration
number

Total duration of the media file in seconds.

language
string

BCP 47 language code of the transcribed audio, as detected or specified.

download_url
string <uri>

Pre-signed URL to download the full transcription file. Valid for a limited time.

Array of objects (Segment)

Time-aligned transcript segments. Present when timestamps was enabled.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed text for this time range.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

Response samples

Content type
{}

Translation

Operations related to translating text or document content between languages

Translation job lifecycle event Webhook

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
event
required
string
Enum: "translation.progress" "translation.completed" "translation.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the translation job.

type
string
Value: "translation-job"

Resource type identifier. Always translation-job.

object (translation_Attributes)

Full attributes of a translation job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (translation_Input)

Source content to translate.

object (translation_Options)

Optional settings controlling translation behaviour.

policy_id
string <uuid> (PolicyId)

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.

object (translation_Result)

Translation output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Responses

Request samples

Content type
application/json
{
  • "event": "translation.completed",
  • "data": {
    • "id": "9a1bc2f3-d405-4678-bcde-f12345678901",
    • "type": "translation-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "source_language": "auto",
        • "formality": "formal",
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Create translation job

Usage is returned in data.attributes.result.usage once the job completes, but only when data.attributes.options.include_usage is true.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
required
object

JSON:API-style data envelope.

type
required
string

Resource type identifier. Must be translation-job.

required
object (translation_AttributesCreate)

Input fields required to create a translation job.

required
object (translation_Input)

Source content to translate.

object (translation_Options)

Optional settings controlling translation behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "data": {
    • "type": "translation-job",
    • "attributes": {},
    • "meta": {
      • "client": { }
      }
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "9a1bc2f3-d405-4678-bcde-f12345678901",
    • "type": "translation-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "source_language": "auto",
        • "formality": "formal",
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get translation job

Use the id from the 202 response to POST /v1/translations.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: 9a1bc2f3-d405-4678-bcde-f12345678901

Job UUID returned when the translation was created.

Responses

Response Schema: application/json
object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the translation job.

type
string
Value: "translation-job"

Resource type identifier. Always translation-job.

object (translation_Attributes)

Full attributes of a translation job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (translation_Input)

Source content to translate.

object (translation_Options)

Optional settings controlling translation behaviour.

policy_id
string <uuid> (PolicyId)

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.

object (translation_Result)

Translation output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Response samples

Content type
application/json
{
  • "data": {
    • "id": "9a1bc2f3-d405-4678-bcde-f12345678901",
    • "type": "translation-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "source_language": "auto",
        • "formality": "formal",
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get translation result

Available once status is completed.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: 9a1bc2f3-d405-4678-bcde-f12345678901

Job UUID returned when the translation was created.

Responses

Response Schema:
source_language
string

BCP 47 language code of the source content, as detected or specified.

target_language
string

BCP 47 language code of the translated output.

content
string

Translated text content. Present when input type is text.

download_url
string <uri>

Pre-signed URL to download the translated file. Valid for a limited time. Present when input type is document.

character_count
integer

Number of characters in the source content.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

Response samples

Content type
{}

Video Analysis

Operations related to extracting structured metadata and insights from video content

Video analysis job lifecycle event Webhook

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
event
required
string
Enum: "video-analysis.progress" "video-analysis.completed" "video-analysis.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the video analysis job.

type
string
Value: "video-analysis-job"

Resource type identifier. Always video-analysis-job.

object (video-analysis_Attributes)

Full attributes of a video analysis job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

policy_id
string <uuid> (PolicyId)

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.

object (video-analysis_Result)

Video analysis output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Responses

Request samples

Content type
application/json
{
  • "event": "video-analysis.completed",
  • "data": {
    • "id": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345",
    • "type": "video-analysis-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "auto",
        • "confidence_threshold": 0.7,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "video_metadata": {
          • "duration": 3742.5,
          • "width": 1920,
          • "height": 1080,
          • "frame_rate": 29.97,
          • "format": "mp4",
          • "codec": "h264"
          },
        • "labels": [
          • {
            }
          ],
        • "scenes": [
          • {
            }
          ],
        • "faces": [
          • {
            }
          ],
        • "speech_to_text": [
          • {
            }
          ],
        • "ocr": [
          • {
            }
          ],
        • "content_moderation": {
          • "is_safe": true,
          • "signals": [
            ]
          },
        • "sentiment": {
          • "overall": "positive",
          • "score": 0.62,
          • "instances": [
            ]
          },
        • "topics": [
          • {
            }
          ],
        • "brands": [
          • {
            }
          ],
        • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Create video analysis job

Usage is returned in data.attributes.result.usage once the job completes, but only when data.attributes.options.include_usage is true.

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
required
object

JSON:API-style data envelope.

type
required
string

Resource type identifier. Must be video-analysis-job.

required
object (video-analysis_AttributesCreate)

Input fields required to create a video analysis job.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "data": {}
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345",
    • "type": "video-analysis-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "auto",
        • "confidence_threshold": 0.7,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "video_metadata": {
          • "duration": 3742.5,
          • "width": 1920,
          • "height": 1080,
          • "frame_rate": 29.97,
          • "format": "mp4",
          • "codec": "h264"
          },
        • "labels": [
          • {
            }
          ],
        • "scenes": [
          • {
            }
          ],
        • "faces": [
          • {
            }
          ],
        • "speech_to_text": [
          • {
            }
          ],
        • "ocr": [
          • {
            }
          ],
        • "content_moderation": {
          • "is_safe": true,
          • "signals": [
            ]
          },
        • "sentiment": {
          • "overall": "positive",
          • "score": 0.62,
          • "instances": [
            ]
          },
        • "topics": [
          • {
            }
          ],
        • "brands": [
          • {
            }
          ],
        • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get video analysis job

Use the id from the 202 response to POST /v1/video-analyses.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: 3e7dc4b2-91f0-4a1e-8c2d-b56789012345

Job UUID returned when the video analysis was created.

Responses

Response Schema: application/json
object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the video analysis job.

type
string
Value: "video-analysis-job"

Resource type identifier. Always video-analysis-job.

object (video-analysis_Attributes)

Full attributes of a video analysis job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

policy_id
string <uuid> (PolicyId)

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.

object (video-analysis_Result)

Video analysis output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Response samples

Content type
application/json
{
  • "data": {
    • "id": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345",
    • "type": "video-analysis-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "auto",
        • "confidence_threshold": 0.7,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "video_metadata": {
          • "duration": 3742.5,
          • "width": 1920,
          • "height": 1080,
          • "frame_rate": 29.97,
          • "format": "mp4",
          • "codec": "h264"
          },
        • "labels": [
          • {
            }
          ],
        • "scenes": [
          • {
            }
          ],
        • "faces": [
          • {
            }
          ],
        • "speech_to_text": [
          • {
            }
          ],
        • "ocr": [
          • {
            }
          ],
        • "content_moderation": {
          • "is_safe": true,
          • "signals": [
            ]
          },
        • "sentiment": {
          • "overall": "positive",
          • "score": 0.62,
          • "instances": [
            ]
          },
        • "topics": [
          • {
            }
          ],
        • "brands": [
          • {
            }
          ],
        • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get video analysis result

Available once status is completed.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: 3e7dc4b2-91f0-4a1e-8c2d-b56789012345

Job UUID returned when the video analysis was created.

Responses

Response Schema: application/json
object (VideoMetadata)

Technical properties of the processed video file.

duration
number

Total duration of the video in seconds.

width
integer

Video width in pixels.

height
integer

Video height in pixels.

frame_rate
number

Frames per second of the video.

format
string

Container format of the video file.

codec
string

Video codec used for encoding.

Array of objects (LabelDetection)

Detected objects, scenes, and actions. Present when labels was requested.

Array
name
string

Human-readable name of the detected label.

confidence
number [ 0 .. 1 ]

Overall confidence score for this label across the video.

Array of objects (TimedInstance)

Time ranges in which this label was detected.

Array of objects (SceneDetection)

Scene and shot boundaries. Present when scenes was requested.

Array
index
integer

Zero-based position of this scene in the video.

start
number

Start time of the scene in seconds.

end
number

End time of the scene in seconds.

Array of objects (FaceDetection)

Faces detected and tracked across the video. Present when faces was requested.

Array
track_id
integer

Integer identifier grouping all appearances of the same face within this video.

fingerprint
string

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.

Array of objects (TimedInstance)

Time ranges in which this face is visible.

Array of objects (TranscriptSegment)

Speech-to-text segments with speaker identification. Present when speech_to_text was requested.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed speech for this time range.

speaker_id
integer

Integer identifier grouping segments from the same speaker.

language
string

BCP 47 language code detected for this segment.

confidence
number [ 0 .. 1 ]

Confidence score for this transcript segment.

Array of objects (OcrText)

On-screen text extracted from video frames. Present when ocr was requested.

Array
text
string

The detected text string.

confidence
number [ 0 .. 1 ]

Confidence score for this text detection.

language
string

BCP 47 language code of the detected text.

Array of objects (TimedInstance)

Time ranges in which this text is visible on screen.

object (ContentModeration)

Content moderation signals. Present when content_moderation was requested.

is_safe
boolean

Whether the video passed moderation at the requested confidence threshold.

Array of objects (ModerationSignal)

Individual moderation signals detected above the confidence threshold.

Array
label
string
Enum: "explicit_nudity" "suggestive" "violence" "visually_disturbing" "hate_symbols" "tobacco" "alcohol" "gambling"

Machine-readable label identifying the type of flagged content.

confidence
number [ 0 .. 1 ]

Overall confidence score for this signal across the video.

Array of objects (TimedInstance)

Time ranges in which this signal was detected.

object (Sentiment)

Overall tone and sentiment of the video. Present when sentiment was requested.

overall
string
Enum: "positive" "neutral" "negative"

Dominant sentiment across the entire video.

score
number [ -1 .. 1 ]

Aggregate sentiment score from -1 (most negative) to 1 (most positive).

Array of objects (SentimentInstance)

Sentiment variations across the video timeline.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

label
string
Enum: "positive" "neutral" "negative"

Sentiment label for this time range.

score
number [ -1 .. 1 ]

Sentiment score for this time range.

Array of objects (Topic)

Key topics and keywords extracted from the video. Present when topics was requested.

Array
name
string

Topic or keyword name.

confidence
number [ 0 .. 1 ]

Confidence score for this topic.

Array of objects (TimedInstance)

Time ranges in which this topic is relevant.

Array of objects (BrandDetection)

Detected brand logos and visual trademarks. Present when brands was requested.

Array
name
string

Name of the detected brand.

confidence
number [ 0 .. 1 ]

Overall confidence score for this brand detection.

Array of objects (TimedInstance)

Time ranges in which this brand is visible on screen.

summary
string

Natural-language description of the video content. Present when summary was requested.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

Response samples

Content type
application/json
{
  • "video_metadata": {
    • "duration": 3742.5,
    • "width": 1920,
    • "height": 1080,
    • "frame_rate": 29.97,
    • "format": "mp4",
    • "codec": "h264"
    },
  • "labels": [
    • {
      • "name": "Conference room",
      • "confidence": 0.94,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "scenes": [
    • {
      • "index": 3,
      • "start": 42,
      • "end": 78.5
      }
    ],
  • "faces": [
    • {
      • "track_id": 1,
      • "fingerprint": "7hGkL2mXqP9nRsT4vWzA...",
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "speech_to_text": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "text": "Welcome to today's panel discussion on AI safety.",
      • "speaker_id": 0,
      • "language": "en",
      • "confidence": 0.97
      }
    ],
  • "ocr": [
    • {
      • "text": "Q3 Revenue: $4.2M",
      • "confidence": 0.91,
      • "language": "en",
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "content_moderation": {
    • "is_safe": true,
    • "signals": [
      • {
        • "label": "violence",
        • "confidence": 0.82,
        • "instances": [
          • {
            }
          ]
        }
      ]
    },
  • "sentiment": {
    • "overall": "positive",
    • "score": 0.62,
    • "instances": [
      • {
        • "start": 0,
        • "end": 45,
        • "label": "positive",
        • "score": 0.71
        }
      ]
    },
  • "topics": [
    • {
      • "name": "artificial intelligence",
      • "confidence": 0.95,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "brands": [
    • {
      • "name": "Acme Corp",
      • "confidence": 0.88,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
  • "usage": {
    • "input_tokens": 312,
    • "output_tokens": 87,
    • "cost": 0.00088
    }
}

LLM

Operations related to submitting generic language model tasks without coupling to a specific AI vendor or model

LLM task job lifecycle event Webhook

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
event
required
string
Enum: "llm-task.completed" "llm-task.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the LLM task job.

type
string
Value: "llm-task-job"

Resource type identifier. Always llm-task-job.

object (llm-task_Attributes)

Full attributes of an LLM task job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
Text input (object) or Document input (object) (llm-task_Input)
object (llm-task_Options)

Generation settings for the LLM task.

policy_id
string <uuid> (PolicyId)

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.

object (llm-task_Result)

LLM task output. Populated once status is completed.

object (llm-task_Meta)

Metadata envelope for an LLM task job. meta.client is echoed back unchanged from the request. Gateway-internal metadata remains outside the public webhook contract.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Responses

Request samples

Content type
application/json
{
  • "event": "llm-task.completed",
  • "data": {
    • "id": "c3d2e1f0-a4b5-6789-cdef-012345678901",
    • "type": "llm-task-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "content": "• 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": "completed",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Create LLM task job

Usage is returned in data.attributes.result.usage once the job completes, but only when data.attributes.options.include_usage is true. Fields vary by provider (tokens, cost, or both).

Authorizations:
oauth2ClientCredentials
Request Body schema: application/json
required
required
object

JSON:API-style data envelope.

type
required
string

Resource type identifier. Must be llm-task-job.

required
object (llm-task_AttributesCreate)

Input fields required to create an LLM task job.

required
Text input (object) or Document input (object) (llm-task_Input)
object (llm-task_Options)

Generation settings for the LLM task.

object (Webhook)

Destination configuration for job lifecycle notifications.

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "data": {
    • "type": "llm-task-job",
    • "attributes": {
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "webhook": {},
      • "provider": "twelvelabs",
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
      },
    • "meta": {
      • "client": { }
      }
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": "c3d2e1f0-a4b5-6789-cdef-012345678901",
    • "type": "llm-task-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "content": "• 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": "completed",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get LLM task job

Use the id from the 202 response to POST /v1/llm-tasks.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: c3d2e1f0-a4b5-6789-cdef-012345678901

Job UUID returned when the LLM task was created.

Responses

Response Schema: application/json
object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the LLM task job.

type
string
Value: "llm-task-job"

Resource type identifier. Always llm-task-job.

object (llm-task_Attributes)

Full attributes of an LLM task job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
Text input (object) or Document input (object) (llm-task_Input)
object (llm-task_Options)

Generation settings for the LLM task.

policy_id
string <uuid> (PolicyId)

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.

object (llm-task_Result)

LLM task output. Populated once status is completed.

object (llm-task_Meta)

Metadata envelope for an LLM task job. meta.client is echoed back unchanged from the request. Gateway-internal metadata remains outside the public webhook contract.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

Response samples

Content type
application/json
{
  • "data": {
    • "id": "c3d2e1f0-a4b5-6789-cdef-012345678901",
    • "type": "llm-task-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "content": "• 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": "completed",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

Get LLM task result

Available once status is completed.

Authorizations:
oauth2ClientCredentials
path Parameters
id
required
string <uuid>
Example: c3d2e1f0-a4b5-6789-cdef-012345678901

Job UUID returned when the LLM task was created.

Responses

Response Schema: application/json
content
string

The model-generated text produced in response to the prompt.

finish_reason
string
Enum: "completed" "max_tokens"

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.

object (Usage)

Token consumption details for this completion. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

Response samples

Content type
application/json
{
  • "content": "• 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": "completed",
  • "usage": {
    • "input_tokens": 312,
    • "output_tokens": 87,
    • "cost": 0.00088
    }
}

Schemas

Available schemas

ServiceAttributes

name
string

Human-readable name of the service.

description
string

Brief description of what the service does.

endpoint
string

Base API endpoint path for this service.

job_type
string

Resource type discriminator used in the data.type field when creating jobs for this service.

status
string
Enum: "active" "deprecated" "disabled"

Current operational status of the service.

{
  • "name": "Transcription",
  • "description": "Converts audio or video content into structured, time-aligned text.",
  • "endpoint": "/v1/transcriptions",
  • "job_type": "transcription-job",
  • "status": "active"
}

Service

id
string

Unique identifier for the service. Matches the URL path segment used for job creation.

type
string
Value: "service"

Resource type identifier. Always service.

object (ServiceAttributes)

Details of an AI Gateway service.

name
string

Human-readable name of the service.

description
string

Brief description of what the service does.

endpoint
string

Base API endpoint path for this service.

job_type
string

Resource type discriminator used in the data.type field when creating jobs for this service.

status
string
Enum: "active" "deprecated" "disabled"

Current operational status of the service.

{
  • "id": "transcriptions",
  • "type": "service",
  • "attributes": {
    • "name": "Transcription",
    • "description": "Converts audio or video content into structured, time-aligned text.",
    • "endpoint": "/v1/transcriptions",
    • "job_type": "transcription-job",
    • "status": "active"
    }
}

ServiceList

Array of objects (Service)
Array
id
string

Unique identifier for the service. Matches the URL path segment used for job creation.

type
string
Value: "service"

Resource type identifier. Always service.

object (ServiceAttributes)

Details of an AI Gateway service.

{
  • "data": [
    • {
      • "id": "transcriptions",
      • "type": "service",
      • "attributes": {
        • "name": "Transcription",
        • "description": "Converts audio or video content into structured, time-aligned text.",
        • "endpoint": "/v1/transcriptions",
        • "job_type": "transcription-job",
        • "status": "active"
        }
      }
    ]
}

ProviderStatus

string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

"active"

Feature

string (Feature)
Enum: "language_detection" "diarization" "timestamps"

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.

"language_detection"

ProviderLimits

requests_per_minute
integer

Maximum number of requests allowed per minute.

requests_per_day
integer

Maximum number of requests allowed per day.

max_file_size_mb
integer

Maximum input file size in megabytes. Applies to file-based capabilities.

max_duration_seconds
integer

Maximum media duration in seconds. Applies to audio/video capabilities.

{
  • "requests_per_minute": 60,
  • "requests_per_day": 10000,
  • "max_file_size_mb": 500,
  • "max_duration_seconds": 7200
}

ProviderPricing

unit
string
Enum: "per_minute" "per_character" "per_page" "per_request" "per_token"

Billing unit for this capability.

amount
number <double>

Cost per unit.

currency
string

ISO 4217 currency code.

{
  • "unit": "per_minute",
  • "amount": 0.024,
  • "currency": "USD"
}

TranscriptionCapabilities

features
Array of strings (Feature)
Items Enum: "language_detection" "diarization" "timestamps"

Subset of transcription features this provider can handle.

languages
Array of strings

BCP 47 language codes supported for transcription input. Absence of this field means the provider accepts all languages.

object (ProviderLimits)

Usage limits for a provider capability.

requests_per_minute
integer

Maximum number of requests allowed per minute.

requests_per_day
integer

Maximum number of requests allowed per day.

max_file_size_mb
integer

Maximum input file size in megabytes. Applies to file-based capabilities.

max_duration_seconds
integer

Maximum media duration in seconds. Applies to audio/video capabilities.

object (ProviderPricing)

Pricing information for a provider capability.

unit
string
Enum: "per_minute" "per_character" "per_page" "per_request" "per_token"

Billing unit for this capability.

amount
number <double>

Cost per unit.

currency
string

ISO 4217 currency code.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

{
  • "features": [
    • "language_detection",
    • "diarization",
    • "timestamps"
    ],
  • "languages": [
    • "en",
    • "fr",
    • "de",
    • "es",
    • "pt",
    • "nl",
    • "it",
    • "ja",
    • "zh"
    ],
  • "limits": {
    • "requests_per_minute": 60,
    • "requests_per_day": 10000,
    • "max_file_size_mb": 500,
    • "max_duration_seconds": 7200
    },
  • "pricing": {
    • "unit": "per_minute",
    • "amount": 0.024,
    • "currency": "USD"
    },
  • "status": "active"
}

translation_Feature

string (translation_Feature)
Enum: "language_detection" "formality"

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.

"language_detection"

TranslationCapabilities

features
Array of strings (translation_Feature)
Items Enum: "language_detection" "formality"

Subset of translation features this provider can handle.

source_languages
Array of strings

BCP 47 language codes accepted as translation input.

target_languages
Array of strings

BCP 47 language codes that can be produced as translation output.

object (ProviderLimits)

Usage limits for a provider capability.

requests_per_minute
integer

Maximum number of requests allowed per minute.

requests_per_day
integer

Maximum number of requests allowed per day.

max_file_size_mb
integer

Maximum input file size in megabytes. Applies to file-based capabilities.

max_duration_seconds
integer

Maximum media duration in seconds. Applies to audio/video capabilities.

object (ProviderPricing)

Pricing information for a provider capability.

unit
string
Enum: "per_minute" "per_character" "per_page" "per_request" "per_token"

Billing unit for this capability.

amount
number <double>

Cost per unit.

currency
string

ISO 4217 currency code.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

{
  • "features": [
    • "language_detection",
    • "formality"
    ],
  • "source_languages": [
    • "en",
    • "fr",
    • "de",
    • "es",
    • "pt",
    • "nl",
    • "it"
    ],
  • "target_languages": [
    • "fr",
    • "de",
    • "es",
    • "pt",
    • "nl",
    • "it",
    • "ja",
    • "zh"
    ],
  • "limits": {
    • "requests_per_minute": 60,
    • "requests_per_day": 10000,
    • "max_file_size_mb": 500,
    • "max_duration_seconds": 7200
    },
  • "pricing": {
    • "unit": "per_minute",
    • "amount": 0.024,
    • "currency": "USD"
    },
  • "status": "active"
}

video-analysis_Feature

string (video-analysis_Feature)
Enum: "labels" "scenes" "faces" "speech_to_text" "ocr" "content_moderation" "sentiment" "topics" "brands" "summary"

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.

"labels"

VideoAnalysisCapabilities

features
Array of strings (video-analysis_Feature)
Items Enum: "labels" "scenes" "faces" "speech_to_text" "ocr" "content_moderation" "sentiment" "topics" "brands" "summary"

Subset of video analysis features this provider can handle.

object (ProviderLimits)

Usage limits for a provider capability.

requests_per_minute
integer

Maximum number of requests allowed per minute.

requests_per_day
integer

Maximum number of requests allowed per day.

max_file_size_mb
integer

Maximum input file size in megabytes. Applies to file-based capabilities.

max_duration_seconds
integer

Maximum media duration in seconds. Applies to audio/video capabilities.

object (ProviderPricing)

Pricing information for a provider capability.

unit
string
Enum: "per_minute" "per_character" "per_page" "per_request" "per_token"

Billing unit for this capability.

amount
number <double>

Cost per unit.

currency
string

ISO 4217 currency code.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

{
  • "features": [
    • "labels",
    • "scenes",
    • "faces",
    • "speech_to_text",
    • "ocr",
    • "content_moderation",
    • "sentiment",
    • "topics",
    • "brands",
    • "summary"
    ],
  • "limits": {
    • "requests_per_minute": 60,
    • "requests_per_day": 10000,
    • "max_file_size_mb": 500,
    • "max_duration_seconds": 7200
    },
  • "pricing": {
    • "unit": "per_minute",
    • "amount": 0.024,
    • "currency": "USD"
    },
  • "status": "active"
}

LlmTaskCapabilities

models
Array of strings

LLM model identifiers available through this provider.

object (ProviderLimits)

Usage limits for a provider capability.

requests_per_minute
integer

Maximum number of requests allowed per minute.

requests_per_day
integer

Maximum number of requests allowed per day.

max_file_size_mb
integer

Maximum input file size in megabytes. Applies to file-based capabilities.

max_duration_seconds
integer

Maximum media duration in seconds. Applies to audio/video capabilities.

object (ProviderPricing)

Pricing information for a provider capability.

unit
string
Enum: "per_minute" "per_character" "per_page" "per_request" "per_token"

Billing unit for this capability.

amount
number <double>

Cost per unit.

currency
string

ISO 4217 currency code.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

{
  • "models": [
    • "gpt-4o",
    • "gpt-4o-mini"
    ],
  • "limits": {
    • "requests_per_minute": 60,
    • "requests_per_day": 10000,
    • "max_file_size_mb": 500,
    • "max_duration_seconds": 7200
    },
  • "pricing": {
    • "unit": "per_minute",
    • "amount": 0.024,
    • "currency": "USD"
    },
  • "status": "active"
}

ProviderAttributes

name
string

Human-readable name of the provider.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

object

Capabilities offered by this provider per service. Only services supported by this provider appear in this object.

object (TranscriptionCapabilities)

Transcription capabilities offered by this provider.

features
Array of strings (Feature)
Items Enum: "language_detection" "diarization" "timestamps"

Subset of transcription features this provider can handle.

languages
Array of strings

BCP 47 language codes supported for transcription input. Absence of this field means the provider accepts all languages.

object (ProviderLimits)

Usage limits for a provider capability.

object (ProviderPricing)

Pricing information for a provider capability.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

object (TranslationCapabilities)

Translation capabilities offered by this provider.

features
Array of strings (translation_Feature)
Items Enum: "language_detection" "formality"

Subset of translation features this provider can handle.

source_languages
Array of strings

BCP 47 language codes accepted as translation input.

target_languages
Array of strings

BCP 47 language codes that can be produced as translation output.

object (ProviderLimits)

Usage limits for a provider capability.

object (ProviderPricing)

Pricing information for a provider capability.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

object (VideoAnalysisCapabilities)

Video analysis capabilities offered by this provider.

features
Array of strings (video-analysis_Feature)
Items Enum: "labels" "scenes" "faces" "speech_to_text" "ocr" "content_moderation" "sentiment" "topics" "brands" "summary"

Subset of video analysis features this provider can handle.

object (ProviderLimits)

Usage limits for a provider capability.

object (ProviderPricing)

Pricing information for a provider capability.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

object (LlmTaskCapabilities)

LLM task capabilities offered by this provider.

models
Array of strings

LLM model identifiers available through this provider.

object (ProviderLimits)

Usage limits for a provider capability.

object (ProviderPricing)

Pricing information for a provider capability.

status
string (ProviderStatus)
Enum: "active" "degraded" "disabled"

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.

{
  • "name": "TwelveLabs",
  • "status": "active",
  • "services": {
    • "transcriptions": {
      • "features": [
        • "language_detection",
        • "diarization",
        • "timestamps"
        ],
      • "languages": [
        • "en",
        • "fr",
        • "de",
        • "es",
        • "pt",
        • "nl",
        • "it",
        • "ja",
        • "zh"
        ],
      • "limits": {
        • "requests_per_minute": 60,
        • "requests_per_day": 10000,
        • "max_file_size_mb": 500,
        • "max_duration_seconds": 7200
        },
      • "pricing": {
        • "unit": "per_minute",
        • "amount": 0.024,
        • "currency": "USD"
        },
      • "status": "active"
      },
    • "translations": {
      • "features": [
        • "language_detection",
        • "formality"
        ],
      • "source_languages": [
        • "en",
        • "fr",
        • "de",
        • "es",
        • "pt",
        • "nl",
        • "it"
        ],
      • "target_languages": [
        • "fr",
        • "de",
        • "es",
        • "pt",
        • "nl",
        • "it",
        • "ja",
        • "zh"
        ],
      • "limits": {
        • "requests_per_minute": 60,
        • "requests_per_day": 10000,
        • "max_file_size_mb": 500,
        • "max_duration_seconds": 7200
        },
      • "pricing": {
        • "unit": "per_minute",
        • "amount": 0.024,
        • "currency": "USD"
        },
      • "status": "active"
      },
    • "video-analyses": {
      • "features": [
        • "labels",
        • "scenes",
        • "faces",
        • "speech_to_text",
        • "ocr",
        • "content_moderation",
        • "sentiment",
        • "topics",
        • "brands",
        • "summary"
        ],
      • "limits": {
        • "requests_per_minute": 60,
        • "requests_per_day": 10000,
        • "max_file_size_mb": 500,
        • "max_duration_seconds": 7200
        },
      • "pricing": {
        • "unit": "per_minute",
        • "amount": 0.024,
        • "currency": "USD"
        },
      • "status": "active"
      },
    • "llm-tasks": {
      • "models": [
        • "gpt-4o",
        • "gpt-4o-mini"
        ],
      • "limits": {
        • "requests_per_minute": 60,
        • "requests_per_day": 10000,
        • "max_file_size_mb": 500,
        • "max_duration_seconds": 7200
        },
      • "pricing": {
        • "unit": "per_minute",
        • "amount": 0.024,
        • "currency": "USD"
        },
      • "status": "active"
      }
    }
}

ProviderList

Array of objects
Array
id
string

Unique identifier for the provider.

type
string
Value: "provider"
object (ProviderAttributes)

Capabilities of a provider across all supported services.

{
  • "data": [
    • {
      • "id": "twelvelabs",
      • "type": "provider",
      • "attributes": {
        • "name": "TwelveLabs",
        • "status": "active",
        • "services": {
          • "transcriptions": {
            },
          • "translations": {
            },
          • "video-analyses": {
            },
          • "llm-tasks": {
            }
          }
        }
      }
    ]
}

JobStatus

string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

"processing"

Provider

string (Provider)

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.

"twelvelabs"

Error

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

{
  • "code": "AUDIO_UNREADABLE",
  • "message": "Could not extract audio from the provided file."
}

RoutingInfo

provider_id
required
string

Identifier of the provider selected to process this job.

reason
required
string
Enum: "explicit_choice" "policy_rule" "failover" "default"

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.

policy_id
string <uuid>

ID of the policy that determined provider selection. Present only when reason is policy_rule.

policy_version
integer >= 1

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.

policy_source
string
Enum: "explicit_id" "tenant_default" "tenant_latest" "global_latest" "none"

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).

attempt
required
integer >= 1

Which attempt this is (1-based). Values greater than 1 indicate a failover retry.

{
  • "provider_id": "eden-ai",
  • "reason": "policy_rule",
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
  • "policy_version": 3,
  • "policy_source": "tenant_default",
  • "attempt": 1
}

Attributes

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string (Provider)

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

object (RoutingInfo)

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.

provider_id
required
string

Identifier of the provider selected to process this job.

reason
required
string
Enum: "explicit_choice" "policy_rule" "failover" "default"

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.

policy_id
string <uuid>

ID of the policy that determined provider selection. Present only when reason is policy_rule.

policy_version
integer >= 1

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.

policy_source
string
Enum: "explicit_id" "tenant_default" "tenant_latest" "global_latest" "none"

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).

attempt
required
integer >= 1

Which attempt this is (1-based). Values greater than 1 indicate a failover retry.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

{
  • "tenant": "acme-corp",
  • "user_id": "auth0|64a1b2c3d4e5f6789012345",
  • "provider": "twelvelabs",
  • "status": "processing",
  • "progress": 72,
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    },
  • "routing": {
    • "provider_id": "eden-ai",
    • "reason": "policy_rule",
    • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "policy_version": 3,
    • "policy_source": "tenant_default",
    • "attempt": 1
    },
  • "created_at": "2024-03-15T10:00:00Z",
  • "processed_at": "2024-03-15T10:00:05Z",
  • "completed_at": "2024-03-15T10:02:30Z"
}

ListMeta

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

{
  • "total": 142,
  • "page_count": 8,
  • "page": 2,
  • "per_page": 20
}

JobList

required
Array of objects
Array
id
string <uuid>

Unique identifier for the job.

type
string

Resource type discriminator identifying the service this job belongs to. One of transcription-job, translation-job, video-analysis-job, llm-task-job.

object (Attributes)

Base attributes shared by all asynchronous job types.

required
object (ListMeta)

Metadata included in all JSON:API collection responses.

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

required
object (PaginationLinks)

JSON:API pagination links included in all collection responses.

self
required
string <uri>

The current page.

first
required
string <uri>

The first page.

prev
required
string or null <uri>

The previous page. Null when on the first page.

next
required
string or null <uri>

The next page. Null when on the last page.

last
required
string <uri>

The last page.

{
  • "data": [
    • {
      • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
      • "type": "transcription-job",
      • "attributes": {
        • "tenant": "acme-corp",
        • "user_id": "auth0|64a1b2c3d4e5f6789012345",
        • "provider": "twelvelabs",
        • "status": "processing",
        • "progress": 72,
        • "error": {
          • "code": "AUDIO_UNREADABLE",
          • "message": "Could not extract audio from the provided file."
          },
        • "routing": {
          • "provider_id": "eden-ai",
          • "reason": "policy_rule",
          • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
          • "policy_version": 3,
          • "policy_source": "tenant_default",
          • "attempt": 1
          },
        • "created_at": "2024-03-15T10:00:00Z",
        • "processed_at": "2024-03-15T10:00:05Z",
        • "completed_at": "2024-03-15T10:02:30Z"
        }
      }
    ],
  • "meta": {
    • "total": 142,
    • "page_count": 8,
    • "page": 2,
    • "per_page": 20
    },
  • "links": {}
}

ErrorResponse

object (Error)

Details of a job failure. Only present when status is failed.

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

{
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    }
}

TenantServiceConfig

enabled
required
boolean

Whether this service is available to the tenant.

{
  • "enabled": true
}

TenantProviderConfig

enabled
required
boolean

Whether this provider is available to the tenant.

{
  • "enabled": true
}

TenantAttributes

object

Per-service access configuration for this tenant. Keys are service IDs (e.g. transcriptions). Services absent from this map inherit the default access policy.

additional property
object (TenantServiceConfig)

Access configuration for a single service within a tenant.

enabled
required
boolean

Whether this service is available to the tenant.

object

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.

additional property
object (TenantProviderConfig)

Access configuration for a single provider within a tenant.

enabled
required
boolean

Whether this provider is available to the tenant.

{
  • "services": {
    • "transcriptions": {
      • "enabled": true
      },
    • "translations": {
      • "enabled": false
      }
    },
  • "providers": {
    • "eden-ai": {
      • "enabled": true
      },
    • "twelvelabs": {
      • "enabled": false
      }
    }
}

Tenant

id
string

Unique slug identifier for the tenant.

type
string
Value: "tenant"

Resource type identifier. Always tenant.

object (TenantAttributes)

Service and provider access configuration for a tenant.

object

Per-service access configuration for this tenant. Keys are service IDs (e.g. transcriptions). Services absent from this map inherit the default access policy.

additional property
object (TenantServiceConfig)

Access configuration for a single service within a tenant.

enabled
required
boolean

Whether this service is available to the tenant.

object

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.

additional property
object (TenantProviderConfig)

Access configuration for a single provider within a tenant.

enabled
required
boolean

Whether this provider is available to the tenant.

{
  • "id": "acme-corp",
  • "type": "tenant",
  • "attributes": {
    • "services": {
      • "transcriptions": {
        • "enabled": true
        },
      • "translations": {
        • "enabled": false
        }
      },
    • "providers": {
      • "eden-ai": {
        • "enabled": true
        },
      • "twelvelabs": {
        • "enabled": false
        }
      }
    }
}

TenantList

required
Array of objects (Tenant)
Array
id
string

Unique slug identifier for the tenant.

type
string
Value: "tenant"

Resource type identifier. Always tenant.

object (TenantAttributes)

Service and provider access configuration for a tenant.

required
object (ListMeta)

Metadata included in all JSON:API collection responses.

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

required
object (PaginationLinks)

JSON:API pagination links included in all collection responses.

self
required
string <uri>

The current page.

first
required
string <uri>

The first page.

prev
required
string or null <uri>

The previous page. Null when on the first page.

next
required
string or null <uri>

The next page. Null when on the last page.

last
required
string <uri>

The last page.

{}

TenantAccessUpdateRequest

required
object
id
required
string

Slug of the tenant being updated. Must match the {slug} path parameter.

type
required
string
Value: "tenant"
required
object

Partial access configuration to apply.

object

Service access overrides. Each key is a service ID; the value sets enabled for that service. Services not included in the map are unchanged.

object

Provider access overrides. Each key is a provider ID; the value sets enabled for that provider. Providers not included in the map are unchanged.

{
  • "data": {
    • "id": "acme-corp",
    • "type": "tenant",
    • "attributes": {
      • "services": {
        • "translations": {
          • "enabled": true
          }
        },
      • "providers": {
        • "twelvelabs": {
          • "enabled": true
          }
        }
      }
    }
}

PolicyProvider

provider_id
required
string

Identifier of the provider.

priority
required
integer >= 1

Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.

weight
integer >= 1

Relative weight for load distribution. Used when routing_strategy is round_robin; ignored otherwise.

object

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.

max_file_size_mb
integer

Only route to this provider when the input file is smaller than this threshold (in MB).

languages
Array of strings

Only route to this provider when the job targets one of these BCP 47 language codes.

{
  • "provider_id": "eden-ai",
  • "priority": 1,
  • "weight": 3,
  • "conditions": {
    • "max_file_size_mb": 200,
    • "languages": [
      • "en",
      • "fr",
      • "de"
      ]
    }
}

PolicyAttributes

tenant
string or null

Slug of the tenant this policy is scoped to. null means the policy is a gateway-wide default, visible to super-admins only.

name
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

version
integer >= 1

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.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"

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.

services
Array of strings

Service IDs this policy applies to (e.g. transcriptions, translations). An empty array or absent field means the policy applies to all services.

Array of objects (PolicyProvider)

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.

Array
provider_id
required
string

Identifier of the provider.

priority
required
integer >= 1

Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.

weight
integer >= 1

Relative weight for load distribution. Used when routing_strategy is round_robin; ignored otherwise.

object

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.

created_at
string <date-time>

When the policy was first created.

updated_at
string <date-time>

When the policy was last updated (i.e. when the current version was created).

{
  • "tenant": "acme-corp",
  • "name": "Cost-optimised production",
  • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
  • "version": 3,
  • "routing_strategy": "price",
  • "services": [
    • "transcriptions",
    • "translations"
    ],
  • "providers": [
    • {
      • "provider_id": "eden-ai",
      • "priority": 1,
      • "weight": 3,
      • "conditions": {
        • "max_file_size_mb": 200,
        • "languages": [
          • "en",
          • "fr",
          • "de"
          ]
        }
      }
    ],
  • "created_at": "2024-03-15T10:00:00Z",
  • "updated_at": "2024-03-16T09:45:00Z"
}

Policy

id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

tenant
string or null

Slug of the tenant this policy is scoped to. null means the policy is a gateway-wide default, visible to super-admins only.

name
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

version
integer >= 1

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.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"

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.

services
Array of strings

Service IDs this policy applies to (e.g. transcriptions, translations). An empty array or absent field means the policy applies to all services.

Array of objects (PolicyProvider)

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.

Array
provider_id
required
string

Identifier of the provider.

priority
required
integer >= 1

Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.

weight
integer >= 1

Relative weight for load distribution. Used when routing_strategy is round_robin; ignored otherwise.

object

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.

created_at
string <date-time>

When the policy was first created.

updated_at
string <date-time>

When the policy was last updated (i.e. when the current version was created).

{
  • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
  • "type": "policy",
  • "attributes": {
    • "tenant": "acme-corp",
    • "name": "Cost-optimised production",
    • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
    • "version": 3,
    • "routing_strategy": "price",
    • "services": [
      • "transcriptions",
      • "translations"
      ],
    • "providers": [
      • {
        • "provider_id": "eden-ai",
        • "priority": 1,
        • "weight": 3,
        • "conditions": {
          • "max_file_size_mb": 200,
          • "languages": [
            ]
          }
        }
      ],
    • "created_at": "2024-03-15T10:00:00Z",
    • "updated_at": "2024-03-16T09:45:00Z"
    }
}

PolicyList

required
Array of objects (Policy)
Array
id
string <uuid>

Unique identifier for the policy.

type
string
Value: "policy"

Resource type identifier. Always policy.

object (PolicyAttributes)

Configuration and metadata for a routing policy.

required
object (ListMeta)

Metadata included in all JSON:API collection responses.

total
required
integer

Total number of items matching the current filters.

page_count
integer

Total number of pages for the current page size.

page
integer

Current page number (1-based).

per_page
integer

Number of items per page used for this response.

required
object (PaginationLinks)

JSON:API pagination links included in all collection responses.

self
required
string <uri>

The current page.

first
required
string <uri>

The first page.

prev
required
string or null <uri>

The previous page. Null when on the first page.

next
required
string or null <uri>

The next page. Null when on the last page.

last
required
string <uri>

The last page.

{
  • "data": [
    • {
      • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "type": "policy",
      • "attributes": {
        • "tenant": "acme-corp",
        • "name": "Cost-optimised production",
        • "description": "Routes jobs to the cheapest available provider first, with fallback to quality-ranked alternatives.",
        • "version": 3,
        • "routing_strategy": "price",
        • "services": [
          • "transcriptions",
          • "translations"
          ],
        • "providers": [
          • {
            }
          ],
        • "created_at": "2024-03-15T10:00:00Z",
        • "updated_at": "2024-03-16T09:45:00Z"
        }
      }
    ],
  • "meta": {
    • "total": 142,
    • "page_count": 8,
    • "page": 2,
    • "per_page": 20
    },
  • "links": {}
}

PolicyCreateAttributes

tenant
string

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.

name
required
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

routing_strategy
required
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Service IDs this policy applies to. Omit to apply to all services.

required
Array of objects (PolicyProvider) non-empty

Ordered provider list. Must contain at least one entry.

Array (non-empty)
provider_id
required
string

Identifier of the provider.

priority
required
integer >= 1

Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.

weight
integer >= 1

Relative weight for load distribution. Used when routing_strategy is round_robin; ignored otherwise.

object

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.

{
  • "tenant": "acme-corp",
  • "name": "Cost-optimised production",
  • "description": "string",
  • "routing_strategy": "price",
  • "services": [
    • "string"
    ],
  • "providers": [
    • {
      • "provider_id": "eden-ai",
      • "priority": 1,
      • "weight": 3,
      • "conditions": {
        • "max_file_size_mb": 200,
        • "languages": [
          • "en",
          • "fr",
          • "de"
          ]
        }
      }
    ]
}

PolicyCreateRequest

required
object
type
required
string
Value: "policy"
required
object (PolicyCreateAttributes)
tenant
string

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.

name
required
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

routing_strategy
required
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Service IDs this policy applies to. Omit to apply to all services.

required
Array of objects (PolicyProvider) non-empty

Ordered provider list. Must contain at least one entry.

{
  • "data": {
    • "type": "policy",
    • "attributes": {
      • "tenant": "acme-corp",
      • "name": "Cost-optimised production",
      • "description": "string",
      • "routing_strategy": "price",
      • "services": [
        • "string"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ]
      }
    }
}

PolicyReplaceAttributes

name
required
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

routing_strategy
required
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Service IDs this policy applies to. Omit or pass empty array to apply to all services.

required
Array of objects (PolicyProvider) non-empty

Full ordered provider list. Must contain at least one entry.

Array (non-empty)
provider_id
required
string

Identifier of the provider.

priority
required
integer >= 1

Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.

weight
integer >= 1

Relative weight for load distribution. Used when routing_strategy is round_robin; ignored otherwise.

object

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.

{
  • "name": "Cost-optimised production",
  • "description": "string",
  • "routing_strategy": "price",
  • "services": [
    • "string"
    ],
  • "providers": [
    • {
      • "provider_id": "eden-ai",
      • "priority": 1,
      • "weight": 3,
      • "conditions": {
        • "max_file_size_mb": 200,
        • "languages": [
          • "en",
          • "fr",
          • "de"
          ]
        }
      }
    ]
}

PolicyReplaceRequest

required
object
id
required
string <uuid>

UUID of the policy being replaced. Must match the {id} path parameter.

type
required
string
Value: "policy"
required
object (PolicyReplaceAttributes)
name
required
string

Human-readable name of the policy.

description
string

Describes the intent or scope of this policy.

routing_strategy
required
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Service IDs this policy applies to. Omit or pass empty array to apply to all services.

required
Array of objects (PolicyProvider) non-empty

Full ordered provider list. Must contain at least one entry.

{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "name": "Cost-optimised production",
      • "description": "string",
      • "routing_strategy": "price",
      • "services": [
        • "string"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ]
      }
    }
}

PolicyPatchAttributes

name
string

New name for the policy.

description
string

New description for the policy.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Replaces the full list of applicable services.

Array of objects (PolicyProvider) non-empty

Replaces the full ordered provider list. Must contain at least one entry if provided.

Array (non-empty)
provider_id
required
string

Identifier of the provider.

priority
required
integer >= 1

Priority rank used for ordered selection. Lower value means higher priority. Must be unique within the policy.

weight
integer >= 1

Relative weight for load distribution. Used when routing_strategy is round_robin; ignored otherwise.

object

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.

{
  • "name": "string",
  • "description": "string",
  • "routing_strategy": "latency",
  • "services": [
    • "string"
    ],
  • "providers": [
    • {
      • "provider_id": "eden-ai",
      • "priority": 1,
      • "weight": 3,
      • "conditions": {
        • "max_file_size_mb": 200,
        • "languages": [
          • "en",
          • "fr",
          • "de"
          ]
        }
      }
    ]
}

PolicyPatchRequest

required
object
id
required
string <uuid>

UUID of the policy being updated. Must match the {id} path parameter.

type
required
string
Value: "policy"
required
object (PolicyPatchAttributes)

Fields to update. All fields are optional; only provided fields are changed.

name
string

New name for the policy.

description
string

New description for the policy.

routing_strategy
string
Enum: "latency" "quality" "price" "round_robin"
services
Array of strings

Replaces the full list of applicable services.

Array of objects (PolicyProvider) non-empty

Replaces the full ordered provider list. Must contain at least one entry if provided.

{
  • "data": {
    • "id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "type": "policy",
    • "attributes": {
      • "name": "string",
      • "description": "string",
      • "routing_strategy": "latency",
      • "services": [
        • "string"
        ],
      • "providers": [
        • {
          • "provider_id": "eden-ai",
          • "priority": 1,
          • "weight": 3,
          • "conditions": {
            }
          }
        ]
      }
    }
}

Input

type
required
string
Enum: "video" "audio"

Media kind. video — audio is extracted from the container, then transcribed (two-step pipeline). audio — the file is transcribed directly.

url
required
string <uri>

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).

audio_track
integer

Zero-based index of the audio track to transcribe when type is video. Omit to use the first audio track. Ignored for type audio.

{}

Options

language
string

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.

timestamps
boolean
Default: true

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).

format
string
Enum: "srt" "vtt" "json"

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.

diarization
boolean
Default: false

When true, requests speaker diarization (who spoke when). Support depends on the provider; see diarization under transcription features in GET /v1/providers.

priority
string
Default: "standard"
Enum: "low" "standard" "high"

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.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

{
  • "language": "en",
  • "timestamps": true,
  • "format": "json",
  • "diarization": false,
  • "priority": "standard",
  • "include_usage": true
}

Webhook

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
{}

PolicyId

string <uuid> (PolicyId)

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.

"f4a3b2c1-d5e6-7890-abcd-ef1234567890"

AttributesCreate

required
object (Input)

Source audio or video file to transcribe.

type
required
string
Enum: "video" "audio"

Media kind. video — audio is extracted from the container, then transcribed (two-step pipeline). audio — the file is transcribed directly.

url
required
string <uri>

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).

audio_track
integer

Zero-based index of the audio track to transcribe when type is video. Omit to use the first audio track. Ignored for type audio.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

language
string

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.

timestamps
boolean
Default: true

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).

format
string
Enum: "srt" "vtt" "json"

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.

diarization
boolean
Default: false

When true, requests speaker diarization (who spoke when). Support depends on the provider; see diarization under transcription features in GET /v1/providers.

priority
string
Default: "standard"
Enum: "low" "standard" "high"

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.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (transcription.progress, transcription.completed, transcription.failed).

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

{
  • "input": {},
  • "options": {
    • "language": "en",
    • "timestamps": true,
    • "format": "json",
    • "diarization": false,
    • "priority": "standard",
    • "include_usage": true
    },
  • "provider": "twelvelabs",
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
}

Meta

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

property name*
additional property
any
object

Internal metadata added by the gateway. Never exposed in webhook payloads.

property name*
additional property
any
{
  • "client": { },
  • "system": {
    • "region": "eu-west-1",
    • "worker_id": "wk_789"
    }
}

CreateRequest

required
object

JSON:API-style resource envelope. Must include type and attributes; meta is optional.

type
required
string

Resource type discriminator. Must be exactly transcription-job for this endpoint.

required
object (AttributesCreate)

Parameters that control what is transcribed and how. Only input is required; configure options, webhook, and provider as needed.

required
object (Input)

Source audio or video file to transcribe.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

object (Webhook)

Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (transcription.progress, transcription.completed, transcription.failed).

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Optional client metadata (meta.client). Stored with the job and returned unchanged in GET responses and webhook payloads. Not used for routing or processing.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{}

Segment

start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed text for this time range.

{
  • "start": 12.5,
  • "end": 15.8,
  • "text": "Welcome to today's interview."
}

Usage

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "input_tokens": 312,
  • "output_tokens": 87,
  • "cost": 0.00088
}

Result

format
string
Enum: "srt" "vtt" "json"

Format of the transcription result, matching the requested output format.

duration
number

Total duration of the media file in seconds.

language
string

BCP 47 language code of the transcribed audio, as detected or specified.

download_url
string <uri>

Pre-signed URL to download the full transcription file. Valid for a limited time.

Array of objects (Segment)

Time-aligned transcript segments. Present when timestamps was enabled.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed text for this time range.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{}

transcription_Attributes

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

object (RoutingInfo)

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.

provider_id
required
string

Identifier of the provider selected to process this job.

reason
required
string
Enum: "explicit_choice" "policy_rule" "failover" "default"

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.

policy_id
string <uuid>

ID of the policy that determined provider selection. Present only when reason is policy_rule.

policy_version
integer >= 1

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.

policy_source
string
Enum: "explicit_id" "tenant_default" "tenant_latest" "global_latest" "none"

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).

attempt
required
integer >= 1

Which attempt this is (1-based). Values greater than 1 indicate a failover retry.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (Input)

Source audio or video file to transcribe.

type
required
string
Enum: "video" "audio"

Media kind. video — audio is extracted from the container, then transcribed (two-step pipeline). audio — the file is transcribed directly.

url
required
string <uri>

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).

audio_track
integer

Zero-based index of the audio track to transcribe when type is video. Omit to use the first audio track. Ignored for type audio.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

language
string

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.

timestamps
boolean
Default: true

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).

format
string
Enum: "srt" "vtt" "json"

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.

diarization
boolean
Default: false

When true, requests speaker diarization (who spoke when). Support depends on the provider; see diarization under transcription features in GET /v1/providers.

priority
string
Default: "standard"
Enum: "low" "standard" "high"

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.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (transcription.progress, transcription.completed, transcription.failed).

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
policy_id
string <uuid> (PolicyId)

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.

object (Result)

Transcription output. Populated once status is completed.

format
string
Enum: "srt" "vtt" "json"

Format of the transcription result, matching the requested output format.

duration
number

Total duration of the media file in seconds.

language
string

BCP 47 language code of the transcribed audio, as detected or specified.

download_url
string <uri>

Pre-signed URL to download the full transcription file. Valid for a limited time.

Array of objects (Segment)

Time-aligned transcript segments. Present when timestamps was enabled.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed text for this time range.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "tenant": "acme-corp",
  • "user_id": "auth0|64a1b2c3d4e5f6789012345",
  • "provider": "twelvelabs",
  • "status": "processing",
  • "progress": 72,
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    },
  • "routing": {
    • "provider_id": "eden-ai",
    • "reason": "policy_rule",
    • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "policy_version": 3,
    • "policy_source": "tenant_default",
    • "attempt": 1
    },
  • "created_at": "2024-03-15T10:00:00Z",
  • "processed_at": "2024-03-15T10:00:05Z",
  • "completed_at": "2024-03-15T10:02:30Z",
  • "input": {},
  • "options": {
    • "language": "en",
    • "timestamps": true,
    • "format": "json",
    • "diarization": false,
    • "priority": "standard",
    • "include_usage": true
    },
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
  • "result": {}
}

Job

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the transcription job.

type
string
Value: "transcription-job"

Resource type identifier. Always transcription-job.

object (transcription_Attributes)

Full attributes of a transcription job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (Input)

Source audio or video file to transcribe.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

object (Webhook)

Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (transcription.progress, transcription.completed, transcription.failed).

policy_id
string <uuid> (PolicyId)

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.

object (Result)

Transcription output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
    • "type": "transcription-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "en",
        • "timestamps": true,
        • "format": "json",
        • "diarization": false,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

translation_Input

type
required
string
Enum: "text" "document"

Type of the source content.

content
string

The text content to translate. Required when type is text.

url
string <uri>

Publicly accessible URL of the document to translate. Required when type is document.

target_language
required
string

BCP 47 language code of the target language.

{}

translation_Options

source_language
string

BCP 47 language code of the source content. Use auto to detect the language automatically.

formality
string
Enum: "default" "formal" "informal"

Formality level of the translated output.

priority
string
Enum: "low" "standard" "high"

Processing priority. Higher priority jobs are picked up sooner.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

{
  • "source_language": "auto",
  • "formality": "formal",
  • "priority": "standard",
  • "include_usage": true
}

translation_AttributesCreate

required
object (translation_Input)

Source content to translate.

type
required
string
Enum: "text" "document"

Type of the source content.

content
string

The text content to translate. Required when type is text.

url
string <uri>

Publicly accessible URL of the document to translate. Required when type is document.

target_language
required
string

BCP 47 language code of the target language.

object (translation_Options)

Optional settings controlling translation behaviour.

source_language
string

BCP 47 language code of the source content. Use auto to detect the language automatically.

formality
string
Enum: "default" "formal" "informal"

Formality level of the translated output.

priority
string
Enum: "low" "standard" "high"

Processing priority. Higher priority jobs are picked up sooner.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Destination configuration for job lifecycle notifications.

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

{
  • "input": {},
  • "options": {
    • "source_language": "auto",
    • "formality": "formal",
    • "priority": "standard",
    • "include_usage": true
    },
  • "provider": "twelvelabs",
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
}

translation_CreateRequest

required
object

JSON:API-style data envelope.

type
required
string

Resource type identifier. Must be translation-job.

required
object (translation_AttributesCreate)

Input fields required to create a translation job.

required
object (translation_Input)

Source content to translate.

object (translation_Options)

Optional settings controlling translation behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "type": "translation-job",
    • "attributes": {
      • "input": {},
      • "options": {
        • "source_language": "auto",
        • "formality": "formal",
        • "priority": "standard",
        • "include_usage": true
        },
      • "provider": "twelvelabs",
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

translation_Result

source_language
string

BCP 47 language code of the source content, as detected or specified.

target_language
string

BCP 47 language code of the translated output.

content
string

Translated text content. Present when input type is text.

download_url
string <uri>

Pre-signed URL to download the translated file. Valid for a limited time. Present when input type is document.

character_count
integer

Number of characters in the source content.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{}

translation_Attributes

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

object (RoutingInfo)

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.

provider_id
required
string

Identifier of the provider selected to process this job.

reason
required
string
Enum: "explicit_choice" "policy_rule" "failover" "default"

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.

policy_id
string <uuid>

ID of the policy that determined provider selection. Present only when reason is policy_rule.

policy_version
integer >= 1

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.

policy_source
string
Enum: "explicit_id" "tenant_default" "tenant_latest" "global_latest" "none"

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).

attempt
required
integer >= 1

Which attempt this is (1-based). Values greater than 1 indicate a failover retry.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (translation_Input)

Source content to translate.

type
required
string
Enum: "text" "document"

Type of the source content.

content
string

The text content to translate. Required when type is text.

url
string <uri>

Publicly accessible URL of the document to translate. Required when type is document.

target_language
required
string

BCP 47 language code of the target language.

object (translation_Options)

Optional settings controlling translation behaviour.

source_language
string

BCP 47 language code of the source content. Use auto to detect the language automatically.

formality
string
Enum: "default" "formal" "informal"

Formality level of the translated output.

priority
string
Enum: "low" "standard" "high"

Processing priority. Higher priority jobs are picked up sooner.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Destination configuration for job lifecycle notifications.

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
policy_id
string <uuid> (PolicyId)

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.

object (translation_Result)

Translation output. Populated once status is completed.

source_language
string

BCP 47 language code of the source content, as detected or specified.

target_language
string

BCP 47 language code of the translated output.

content
string

Translated text content. Present when input type is text.

download_url
string <uri>

Pre-signed URL to download the translated file. Valid for a limited time. Present when input type is document.

character_count
integer

Number of characters in the source content.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "tenant": "acme-corp",
  • "user_id": "auth0|64a1b2c3d4e5f6789012345",
  • "provider": "twelvelabs",
  • "status": "processing",
  • "progress": 72,
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    },
  • "routing": {
    • "provider_id": "eden-ai",
    • "reason": "policy_rule",
    • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "policy_version": 3,
    • "policy_source": "tenant_default",
    • "attempt": 1
    },
  • "created_at": "2024-03-15T10:00:00Z",
  • "processed_at": "2024-03-15T10:00:05Z",
  • "completed_at": "2024-03-15T10:02:30Z",
  • "input": {},
  • "options": {
    • "source_language": "auto",
    • "formality": "formal",
    • "priority": "standard",
    • "include_usage": true
    },
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
  • "result": {}
}

translation_Job

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the translation job.

type
string
Value: "translation-job"

Resource type identifier. Always translation-job.

object (translation_Attributes)

Full attributes of a translation job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (translation_Input)

Source content to translate.

object (translation_Options)

Optional settings controlling translation behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

policy_id
string <uuid> (PolicyId)

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.

object (translation_Result)

Translation output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "id": "9a1bc2f3-d405-4678-bcde-f12345678901",
    • "type": "translation-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "source_language": "auto",
        • "formality": "formal",
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

video-analysis_Input

url
required
string <uri>

Publicly accessible URL of the video file.

features
required
Array of strings (video-analysis_Feature) non-empty
Items Enum: "labels" "scenes" "faces" "speech_to_text" "ocr" "content_moderation" "sentiment" "topics" "brands" "summary"

One or more analysis capabilities to apply. At least one feature must be specified.

audio_track
integer

Index of the audio track to use for speech-related features. Defaults to the first track when omitted.

{}

video-analysis_Options

language
string

BCP 47 language code for speech and text features. Use auto to detect the language automatically.

confidence_threshold
number [ 0 .. 1 ]

Minimum confidence score (0–1) for a detection to be included in the result. Defaults to 0.5.

priority
string
Enum: "low" "standard" "high"

Processing priority. Higher priority jobs are picked up sooner.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

{
  • "language": "auto",
  • "confidence_threshold": 0.7,
  • "priority": "standard",
  • "include_usage": true
}

video-analysis_AttributesCreate

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

url
required
string <uri>

Publicly accessible URL of the video file.

features
required
Array of strings (video-analysis_Feature) non-empty
Items Enum: "labels" "scenes" "faces" "speech_to_text" "ocr" "content_moderation" "sentiment" "topics" "brands" "summary"

One or more analysis capabilities to apply. At least one feature must be specified.

audio_track
integer

Index of the audio track to use for speech-related features. Defaults to the first track when omitted.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

language
string

BCP 47 language code for speech and text features. Use auto to detect the language automatically.

confidence_threshold
number [ 0 .. 1 ]

Minimum confidence score (0–1) for a detection to be included in the result. Defaults to 0.5.

priority
string
Enum: "low" "standard" "high"

Processing priority. Higher priority jobs are picked up sooner.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Destination configuration for job lifecycle notifications.

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

{
  • "input": {},
  • "options": {
    • "language": "auto",
    • "confidence_threshold": 0.7,
    • "priority": "standard",
    • "include_usage": true
    },
  • "provider": "twelvelabs",
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
}

video-analysis_CreateRequest

required
object

JSON:API-style data envelope.

type
required
string

Resource type identifier. Must be video-analysis-job.

required
object (video-analysis_AttributesCreate)

Input fields required to create a video analysis job.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "type": "video-analysis-job",
    • "attributes": {
      • "input": {},
      • "options": {
        • "language": "auto",
        • "confidence_threshold": 0.7,
        • "priority": "standard",
        • "include_usage": true
        },
      • "provider": "twelvelabs",
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

VideoMetadata

duration
number

Total duration of the video in seconds.

width
integer

Video width in pixels.

height
integer

Video height in pixels.

frame_rate
number

Frames per second of the video.

format
string

Container format of the video file.

codec
string

Video codec used for encoding.

{
  • "duration": 3742.5,
  • "width": 1920,
  • "height": 1080,
  • "frame_rate": 29.97,
  • "format": "mp4",
  • "codec": "h264"
}

TimedInstance

start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "start": 12.5,
  • "end": 15.8,
  • "confidence": 0.91
}

LabelDetection

name
string

Human-readable name of the detected label.

confidence
number [ 0 .. 1 ]

Overall confidence score for this label across the video.

Array of objects (TimedInstance)

Time ranges in which this label was detected.

Array
start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "name": "Conference room",
  • "confidence": 0.94,
  • "instances": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "confidence": 0.91
      }
    ]
}

SceneDetection

index
integer

Zero-based position of this scene in the video.

start
number

Start time of the scene in seconds.

end
number

End time of the scene in seconds.

{
  • "index": 3,
  • "start": 42,
  • "end": 78.5
}

FaceDetection

track_id
integer

Integer identifier grouping all appearances of the same face within this video.

fingerprint
string

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.

Array of objects (TimedInstance)

Time ranges in which this face is visible.

Array
start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "track_id": 1,
  • "fingerprint": "7hGkL2mXqP9nRsT4vWzA...",
  • "instances": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "confidence": 0.91
      }
    ]
}

TranscriptSegment

start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed speech for this time range.

speaker_id
integer

Integer identifier grouping segments from the same speaker.

language
string

BCP 47 language code detected for this segment.

confidence
number [ 0 .. 1 ]

Confidence score for this transcript segment.

{
  • "start": 12.5,
  • "end": 15.8,
  • "text": "Welcome to today's panel discussion on AI safety.",
  • "speaker_id": 0,
  • "language": "en",
  • "confidence": 0.97
}

OcrText

text
string

The detected text string.

confidence
number [ 0 .. 1 ]

Confidence score for this text detection.

language
string

BCP 47 language code of the detected text.

Array of objects (TimedInstance)

Time ranges in which this text is visible on screen.

Array
start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "text": "Q3 Revenue: $4.2M",
  • "confidence": 0.91,
  • "language": "en",
  • "instances": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "confidence": 0.91
      }
    ]
}

ModerationSignal

label
string
Enum: "explicit_nudity" "suggestive" "violence" "visually_disturbing" "hate_symbols" "tobacco" "alcohol" "gambling"

Machine-readable label identifying the type of flagged content.

confidence
number [ 0 .. 1 ]

Overall confidence score for this signal across the video.

Array of objects (TimedInstance)

Time ranges in which this signal was detected.

Array
start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "label": "violence",
  • "confidence": 0.82,
  • "instances": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "confidence": 0.91
      }
    ]
}

ContentModeration

is_safe
boolean

Whether the video passed moderation at the requested confidence threshold.

Array of objects (ModerationSignal)

Individual moderation signals detected above the confidence threshold.

Array
label
string
Enum: "explicit_nudity" "suggestive" "violence" "visually_disturbing" "hate_symbols" "tobacco" "alcohol" "gambling"

Machine-readable label identifying the type of flagged content.

confidence
number [ 0 .. 1 ]

Overall confidence score for this signal across the video.

Array of objects (TimedInstance)

Time ranges in which this signal was detected.

{
  • "is_safe": true,
  • "signals": [
    • {
      • "label": "violence",
      • "confidence": 0.82,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ]
}

SentimentInstance

start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

label
string
Enum: "positive" "neutral" "negative"

Sentiment label for this time range.

score
number [ -1 .. 1 ]

Sentiment score for this time range.

{
  • "start": 0,
  • "end": 45,
  • "label": "positive",
  • "score": 0.71
}

Sentiment

overall
string
Enum: "positive" "neutral" "negative"

Dominant sentiment across the entire video.

score
number [ -1 .. 1 ]

Aggregate sentiment score from -1 (most negative) to 1 (most positive).

Array of objects (SentimentInstance)

Sentiment variations across the video timeline.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

label
string
Enum: "positive" "neutral" "negative"

Sentiment label for this time range.

score
number [ -1 .. 1 ]

Sentiment score for this time range.

{
  • "overall": "positive",
  • "score": 0.62,
  • "instances": [
    • {
      • "start": 0,
      • "end": 45,
      • "label": "positive",
      • "score": 0.71
      }
    ]
}

Topic

name
string

Topic or keyword name.

confidence
number [ 0 .. 1 ]

Confidence score for this topic.

Array of objects (TimedInstance)

Time ranges in which this topic is relevant.

Array
start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "name": "artificial intelligence",
  • "confidence": 0.95,
  • "instances": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "confidence": 0.91
      }
    ]
}

BrandDetection

name
string

Name of the detected brand.

confidence
number [ 0 .. 1 ]

Overall confidence score for this brand detection.

Array of objects (TimedInstance)

Time ranges in which this brand is visible on screen.

Array
start
number

Start time of the occurrence in seconds.

end
number

End time of the occurrence in seconds.

confidence
number [ 0 .. 1 ]

Confidence score for this specific occurrence.

{
  • "name": "Acme Corp",
  • "confidence": 0.88,
  • "instances": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "confidence": 0.91
      }
    ]
}

video-analysis_Result

object (VideoMetadata)

Technical properties of the processed video file.

duration
number

Total duration of the video in seconds.

width
integer

Video width in pixels.

height
integer

Video height in pixels.

frame_rate
number

Frames per second of the video.

format
string

Container format of the video file.

codec
string

Video codec used for encoding.

Array of objects (LabelDetection)

Detected objects, scenes, and actions. Present when labels was requested.

Array
name
string

Human-readable name of the detected label.

confidence
number [ 0 .. 1 ]

Overall confidence score for this label across the video.

Array of objects (TimedInstance)

Time ranges in which this label was detected.

Array of objects (SceneDetection)

Scene and shot boundaries. Present when scenes was requested.

Array
index
integer

Zero-based position of this scene in the video.

start
number

Start time of the scene in seconds.

end
number

End time of the scene in seconds.

Array of objects (FaceDetection)

Faces detected and tracked across the video. Present when faces was requested.

Array
track_id
integer

Integer identifier grouping all appearances of the same face within this video.

fingerprint
string

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.

Array of objects (TimedInstance)

Time ranges in which this face is visible.

Array of objects (TranscriptSegment)

Speech-to-text segments with speaker identification. Present when speech_to_text was requested.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed speech for this time range.

speaker_id
integer

Integer identifier grouping segments from the same speaker.

language
string

BCP 47 language code detected for this segment.

confidence
number [ 0 .. 1 ]

Confidence score for this transcript segment.

Array of objects (OcrText)

On-screen text extracted from video frames. Present when ocr was requested.

Array
text
string

The detected text string.

confidence
number [ 0 .. 1 ]

Confidence score for this text detection.

language
string

BCP 47 language code of the detected text.

Array of objects (TimedInstance)

Time ranges in which this text is visible on screen.

object (ContentModeration)

Content moderation signals. Present when content_moderation was requested.

is_safe
boolean

Whether the video passed moderation at the requested confidence threshold.

Array of objects (ModerationSignal)

Individual moderation signals detected above the confidence threshold.

Array
label
string
Enum: "explicit_nudity" "suggestive" "violence" "visually_disturbing" "hate_symbols" "tobacco" "alcohol" "gambling"

Machine-readable label identifying the type of flagged content.

confidence
number [ 0 .. 1 ]

Overall confidence score for this signal across the video.

Array of objects (TimedInstance)

Time ranges in which this signal was detected.

object (Sentiment)

Overall tone and sentiment of the video. Present when sentiment was requested.

overall
string
Enum: "positive" "neutral" "negative"

Dominant sentiment across the entire video.

score
number [ -1 .. 1 ]

Aggregate sentiment score from -1 (most negative) to 1 (most positive).

Array of objects (SentimentInstance)

Sentiment variations across the video timeline.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

label
string
Enum: "positive" "neutral" "negative"

Sentiment label for this time range.

score
number [ -1 .. 1 ]

Sentiment score for this time range.

Array of objects (Topic)

Key topics and keywords extracted from the video. Present when topics was requested.

Array
name
string

Topic or keyword name.

confidence
number [ 0 .. 1 ]

Confidence score for this topic.

Array of objects (TimedInstance)

Time ranges in which this topic is relevant.

Array of objects (BrandDetection)

Detected brand logos and visual trademarks. Present when brands was requested.

Array
name
string

Name of the detected brand.

confidence
number [ 0 .. 1 ]

Overall confidence score for this brand detection.

Array of objects (TimedInstance)

Time ranges in which this brand is visible on screen.

summary
string

Natural-language description of the video content. Present when summary was requested.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "video_metadata": {
    • "duration": 3742.5,
    • "width": 1920,
    • "height": 1080,
    • "frame_rate": 29.97,
    • "format": "mp4",
    • "codec": "h264"
    },
  • "labels": [
    • {
      • "name": "Conference room",
      • "confidence": 0.94,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "scenes": [
    • {
      • "index": 3,
      • "start": 42,
      • "end": 78.5
      }
    ],
  • "faces": [
    • {
      • "track_id": 1,
      • "fingerprint": "7hGkL2mXqP9nRsT4vWzA...",
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "speech_to_text": [
    • {
      • "start": 12.5,
      • "end": 15.8,
      • "text": "Welcome to today's panel discussion on AI safety.",
      • "speaker_id": 0,
      • "language": "en",
      • "confidence": 0.97
      }
    ],
  • "ocr": [
    • {
      • "text": "Q3 Revenue: $4.2M",
      • "confidence": 0.91,
      • "language": "en",
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "content_moderation": {
    • "is_safe": true,
    • "signals": [
      • {
        • "label": "violence",
        • "confidence": 0.82,
        • "instances": [
          • {
            }
          ]
        }
      ]
    },
  • "sentiment": {
    • "overall": "positive",
    • "score": 0.62,
    • "instances": [
      • {
        • "start": 0,
        • "end": 45,
        • "label": "positive",
        • "score": 0.71
        }
      ]
    },
  • "topics": [
    • {
      • "name": "artificial intelligence",
      • "confidence": 0.95,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "brands": [
    • {
      • "name": "Acme Corp",
      • "confidence": 0.88,
      • "instances": [
        • {
          • "start": 12.5,
          • "end": 15.8,
          • "confidence": 0.91
          }
        ]
      }
    ],
  • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
  • "usage": {
    • "input_tokens": 312,
    • "output_tokens": 87,
    • "cost": 0.00088
    }
}

video-analysis_Attributes

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

object (RoutingInfo)

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.

provider_id
required
string

Identifier of the provider selected to process this job.

reason
required
string
Enum: "explicit_choice" "policy_rule" "failover" "default"

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.

policy_id
string <uuid>

ID of the policy that determined provider selection. Present only when reason is policy_rule.

policy_version
integer >= 1

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.

policy_source
string
Enum: "explicit_id" "tenant_default" "tenant_latest" "global_latest" "none"

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).

attempt
required
integer >= 1

Which attempt this is (1-based). Values greater than 1 indicate a failover retry.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

url
required
string <uri>

Publicly accessible URL of the video file.

features
required
Array of strings (video-analysis_Feature) non-empty
Items Enum: "labels" "scenes" "faces" "speech_to_text" "ocr" "content_moderation" "sentiment" "topics" "brands" "summary"

One or more analysis capabilities to apply. At least one feature must be specified.

audio_track
integer

Index of the audio track to use for speech-related features. Defaults to the first track when omitted.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

language
string

BCP 47 language code for speech and text features. Use auto to detect the language automatically.

confidence_threshold
number [ 0 .. 1 ]

Minimum confidence score (0–1) for a detection to be included in the result. Defaults to 0.5.

priority
string
Enum: "low" "standard" "high"

Processing priority. Higher priority jobs are picked up sooner.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Destination configuration for job lifecycle notifications.

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
policy_id
string <uuid> (PolicyId)

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.

object (video-analysis_Result)

Video analysis output. Populated once status is completed.

object (VideoMetadata)

Technical properties of the processed video file.

duration
number

Total duration of the video in seconds.

width
integer

Video width in pixels.

height
integer

Video height in pixels.

frame_rate
number

Frames per second of the video.

format
string

Container format of the video file.

codec
string

Video codec used for encoding.

Array of objects (LabelDetection)

Detected objects, scenes, and actions. Present when labels was requested.

Array
name
string

Human-readable name of the detected label.

confidence
number [ 0 .. 1 ]

Overall confidence score for this label across the video.

Array of objects (TimedInstance)

Time ranges in which this label was detected.

Array of objects (SceneDetection)

Scene and shot boundaries. Present when scenes was requested.

Array
index
integer

Zero-based position of this scene in the video.

start
number

Start time of the scene in seconds.

end
number

End time of the scene in seconds.

Array of objects (FaceDetection)

Faces detected and tracked across the video. Present when faces was requested.

Array
track_id
integer

Integer identifier grouping all appearances of the same face within this video.

fingerprint
string

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.

Array of objects (TimedInstance)

Time ranges in which this face is visible.

Array of objects (TranscriptSegment)

Speech-to-text segments with speaker identification. Present when speech_to_text was requested.

Array
start
number

Start time of the segment in seconds.

end
number

End time of the segment in seconds.

text
string

Transcribed speech for this time range.

speaker_id
integer

Integer identifier grouping segments from the same speaker.

language
string

BCP 47 language code detected for this segment.

confidence
number [ 0 .. 1 ]

Confidence score for this transcript segment.

Array of objects (OcrText)

On-screen text extracted from video frames. Present when ocr was requested.

Array
text
string

The detected text string.

confidence
number [ 0 .. 1 ]

Confidence score for this text detection.

language
string

BCP 47 language code of the detected text.

Array of objects (TimedInstance)

Time ranges in which this text is visible on screen.

object (ContentModeration)

Content moderation signals. Present when content_moderation was requested.

is_safe
boolean

Whether the video passed moderation at the requested confidence threshold.

Array of objects (ModerationSignal)

Individual moderation signals detected above the confidence threshold.

object (Sentiment)

Overall tone and sentiment of the video. Present when sentiment was requested.

overall
string
Enum: "positive" "neutral" "negative"

Dominant sentiment across the entire video.

score
number [ -1 .. 1 ]

Aggregate sentiment score from -1 (most negative) to 1 (most positive).

Array of objects (SentimentInstance)

Sentiment variations across the video timeline.

Array of objects (Topic)

Key topics and keywords extracted from the video. Present when topics was requested.

Array
name
string

Topic or keyword name.

confidence
number [ 0 .. 1 ]

Confidence score for this topic.

Array of objects (TimedInstance)

Time ranges in which this topic is relevant.

Array of objects (BrandDetection)

Detected brand logos and visual trademarks. Present when brands was requested.

Array
name
string

Name of the detected brand.

confidence
number [ 0 .. 1 ]

Overall confidence score for this brand detection.

Array of objects (TimedInstance)

Time ranges in which this brand is visible on screen.

summary
string

Natural-language description of the video content. Present when summary was requested.

object (Usage)

Provider-reported resource consumption. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "tenant": "acme-corp",
  • "user_id": "auth0|64a1b2c3d4e5f6789012345",
  • "provider": "twelvelabs",
  • "status": "processing",
  • "progress": 72,
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    },
  • "routing": {
    • "provider_id": "eden-ai",
    • "reason": "policy_rule",
    • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "policy_version": 3,
    • "policy_source": "tenant_default",
    • "attempt": 1
    },
  • "created_at": "2024-03-15T10:00:00Z",
  • "processed_at": "2024-03-15T10:00:05Z",
  • "completed_at": "2024-03-15T10:02:30Z",
  • "input": {},
  • "options": {
    • "language": "auto",
    • "confidence_threshold": 0.7,
    • "priority": "standard",
    • "include_usage": true
    },
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
  • "result": {
    • "video_metadata": {
      • "duration": 3742.5,
      • "width": 1920,
      • "height": 1080,
      • "frame_rate": 29.97,
      • "format": "mp4",
      • "codec": "h264"
      },
    • "labels": [
      • {
        • "name": "Conference room",
        • "confidence": 0.94,
        • "instances": [
          • {
            }
          ]
        }
      ],
    • "scenes": [
      • {
        • "index": 3,
        • "start": 42,
        • "end": 78.5
        }
      ],
    • "faces": [
      • {
        • "track_id": 1,
        • "fingerprint": "7hGkL2mXqP9nRsT4vWzA...",
        • "instances": [
          • {
            }
          ]
        }
      ],
    • "speech_to_text": [
      • {
        • "start": 12.5,
        • "end": 15.8,
        • "text": "Welcome to today's panel discussion on AI safety.",
        • "speaker_id": 0,
        • "language": "en",
        • "confidence": 0.97
        }
      ],
    • "ocr": [
      • {
        • "text": "Q3 Revenue: $4.2M",
        • "confidence": 0.91,
        • "language": "en",
        • "instances": [
          • {
            }
          ]
        }
      ],
    • "content_moderation": {
      • "is_safe": true,
      • "signals": [
        • {
          • "label": "violence",
          • "confidence": 0.82,
          • "instances": [
            ]
          }
        ]
      },
    • "sentiment": {
      • "overall": "positive",
      • "score": 0.62,
      • "instances": [
        • {
          • "start": 0,
          • "end": 45,
          • "label": "positive",
          • "score": 0.71
          }
        ]
      },
    • "topics": [
      • {
        • "name": "artificial intelligence",
        • "confidence": 0.95,
        • "instances": [
          • {
            }
          ]
        }
      ],
    • "brands": [
      • {
        • "name": "Acme Corp",
        • "confidence": 0.88,
        • "instances": [
          • {
            }
          ]
        }
      ],
    • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
    • "usage": {
      • "input_tokens": 312,
      • "output_tokens": 87,
      • "cost": 0.00088
      }
    }
}

video-analysis_Job

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the video analysis job.

type
string
Value: "video-analysis-job"

Resource type identifier. Always video-analysis-job.

object (video-analysis_Attributes)

Full attributes of a video analysis job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

policy_id
string <uuid> (PolicyId)

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.

object (video-analysis_Result)

Video analysis output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "id": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345",
    • "type": "video-analysis-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "auto",
        • "confidence_threshold": 0.7,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "video_metadata": {
          • "duration": 3742.5,
          • "width": 1920,
          • "height": 1080,
          • "frame_rate": 29.97,
          • "format": "mp4",
          • "codec": "h264"
          },
        • "labels": [
          • {
            }
          ],
        • "scenes": [
          • {
            }
          ],
        • "faces": [
          • {
            }
          ],
        • "speech_to_text": [
          • {
            }
          ],
        • "ocr": [
          • {
            }
          ],
        • "content_moderation": {
          • "is_safe": true,
          • "signals": [
            ]
          },
        • "sentiment": {
          • "overall": "positive",
          • "score": 0.62,
          • "instances": [
            ]
          },
        • "topics": [
          • {
            }
          ],
        • "brands": [
          • {
            }
          ],
        • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

llm-task_Input

One of
type
required
string
Enum: "text" "document"

Type of the source content supplied for the task.

Value: "text"
text
required
string

Inline text content for the model to process.

prompt
required
string

Instruction describing the task the model should perform on the provided content.

system_prompt
string

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.

Example
{
  • "type": "text",
  • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
  • "prompt": "Summarise the following article in three bullet points.",
  • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
}

llm-task_Options

creativity
string
Enum: "precise" "balanced" "creative"

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.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include token usage under data.attributes.result.usage. Omit or set false to hide usage.

{
  • "creativity": "balanced",
  • "include_usage": true
}

llm-task_AttributesCreate

required
Text input (object) or Document input (object) (llm-task_Input)
One of
type
required
string
Enum: "text" "document"

Type of the source content supplied for the task.

Value: "text"
text
required
string

Inline text content for the model to process.

prompt
required
string

Instruction describing the task the model should perform on the provided content.

system_prompt
string

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.

object (llm-task_Options)

Generation settings for the LLM task.

creativity
string
Enum: "precise" "balanced" "creative"

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.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include token usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Destination configuration for job lifecycle notifications.

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

{
  • "input": {
    • "type": "text",
    • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
    • "prompt": "Summarise the following article in three bullet points.",
    • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
    },
  • "options": {
    • "creativity": "balanced",
    • "include_usage": true
    },
  • "provider": "twelvelabs",
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
}

llm-task_CreateRequest

required
object

JSON:API-style data envelope.

type
required
string

Resource type identifier. Must be llm-task-job.

required
object (llm-task_AttributesCreate)

Input fields required to create an LLM task job.

required
Text input (object) or Document input (object) (llm-task_Input)
object (llm-task_Options)

Generation settings for the LLM task.

object (Webhook)

Destination configuration for job lifecycle notifications.

provider
string (Provider)

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.

policy_id
string <uuid> (PolicyId)

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.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "type": "llm-task-job",
    • "attributes": {
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "provider": "twelvelabs",
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890"
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

llm-task_Result

content
string

The model-generated text produced in response to the prompt.

finish_reason
string
Enum: "completed" "max_tokens"

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.

object (Usage)

Token consumption details for this completion. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "content": "• 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": "completed",
  • "usage": {
    • "input_tokens": 312,
    • "output_tokens": 87,
    • "cost": 0.00088
    }
}

llm-task_Attributes

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

code
string

Machine-readable error identifier.

message
string

Human-readable explanation of the error.

object (RoutingInfo)

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.

provider_id
required
string

Identifier of the provider selected to process this job.

reason
required
string
Enum: "explicit_choice" "policy_rule" "failover" "default"

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.

policy_id
string <uuid>

ID of the policy that determined provider selection. Present only when reason is policy_rule.

policy_version
integer >= 1

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.

policy_source
string
Enum: "explicit_id" "tenant_default" "tenant_latest" "global_latest" "none"

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).

attempt
required
integer >= 1

Which attempt this is (1-based). Values greater than 1 indicate a failover retry.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
Text input (object) or Document input (object) (llm-task_Input)
One of
type
required
string
Enum: "text" "document"

Type of the source content supplied for the task.

Value: "text"
text
required
string

Inline text content for the model to process.

prompt
required
string

Instruction describing the task the model should perform on the provided content.

system_prompt
string

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.

object (llm-task_Options)

Generation settings for the LLM task.

creativity
string
Enum: "precise" "balanced" "creative"

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.

include_usage
boolean
Default: false

When true, the completed job response and webhook payload include token usage under data.attributes.result.usage. Omit or set false to hide usage.

object (Webhook)

Destination configuration for job lifecycle notifications.

url
required
string <uri>

The endpoint the gateway will POST event payloads to.

object

Optional HTTP headers included in every webhook request. Typically used for authentication.

property name*
additional property
string
policy_id
string <uuid> (PolicyId)

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.

object (llm-task_Result)

LLM task output. Populated once status is completed.

content
string

The model-generated text produced in response to the prompt.

finish_reason
string
Enum: "completed" "max_tokens"

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.

object (Usage)

Token consumption details for this completion. Present only when options.include_usage was true at submission time.

input_tokens
integer

Number of input tokens consumed, when reported by the provider.

output_tokens
integer

Number of output tokens produced, when reported by the provider.

cost
number

Provider-reported cost in provider billing units, when available.

{
  • "tenant": "acme-corp",
  • "user_id": "auth0|64a1b2c3d4e5f6789012345",
  • "provider": "twelvelabs",
  • "status": "processing",
  • "progress": 72,
  • "error": {
    • "code": "AUDIO_UNREADABLE",
    • "message": "Could not extract audio from the provided file."
    },
  • "routing": {
    • "provider_id": "eden-ai",
    • "reason": "policy_rule",
    • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
    • "policy_version": 3,
    • "policy_source": "tenant_default",
    • "attempt": 1
    },
  • "created_at": "2024-03-15T10:00:00Z",
  • "processed_at": "2024-03-15T10:00:05Z",
  • "completed_at": "2024-03-15T10:02:30Z",
  • "input": {
    • "type": "text",
    • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
    • "prompt": "Summarise the following article in three bullet points.",
    • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
    },
  • "options": {
    • "creativity": "balanced",
    • "include_usage": true
    },
  • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
  • "result": {
    • "content": "• 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": "completed",
    • "usage": {
      • "input_tokens": 312,
      • "output_tokens": 87,
      • "cost": 0.00088
      }
    }
}

llm-task_Meta

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

property name*
additional property
any
object

Internal metadata added by the gateway. Never exposed in webhook payloads.

property name*
additional property
any
{
  • "client": { },
  • "system": {
    • "region": "eu-west-1",
    • "worker_id": "wk_789"
    }
}

llm-task_Job

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the LLM task job.

type
string
Value: "llm-task-job"

Resource type identifier. Always llm-task-job.

object (llm-task_Attributes)

Full attributes of an LLM task job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
Text input (object) or Document input (object) (llm-task_Input)
object (llm-task_Options)

Generation settings for the LLM task.

object (Webhook)

Destination configuration for job lifecycle notifications.

policy_id
string <uuid> (PolicyId)

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.

object (llm-task_Result)

LLM task output. Populated once status is completed.

object (llm-task_Meta)

Metadata envelope for an LLM task job. meta.client is echoed back unchanged from the request. Gateway-internal metadata remains outside the public webhook contract.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "data": {
    • "id": "c3d2e1f0-a4b5-6789-cdef-012345678901",
    • "type": "llm-task-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "content": "• 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": "completed",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

WebhookPayload

event
required
string
Enum: "transcription.progress" "transcription.completed" "transcription.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the transcription job.

type
string
Value: "transcription-job"

Resource type identifier. Always transcription-job.

object (transcription_Attributes)

Full attributes of a transcription job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (Input)

Source audio or video file to transcribe.

object (Options)

Optional transcription settings (language, output format, timestamps, diarization, priority). See the Options schema for field-level details.

object (Webhook)

Optional callback URL. When set, the gateway POSTs JSON payloads on each lifecycle transition (transcription.progress, transcription.completed, transcription.failed).

policy_id
string <uuid> (PolicyId)

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.

object (Result)

Transcription output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "event": "transcription.completed",
  • "data": {
    • "id": "2f41bc1f-b608-4360-acd9-a26a296fea3c",
    • "type": "transcription-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "en",
        • "timestamps": true,
        • "format": "json",
        • "diarization": false,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

translation_WebhookPayload

event
required
string
Enum: "translation.progress" "translation.completed" "translation.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the translation job.

type
string
Value: "translation-job"

Resource type identifier. Always translation-job.

object (translation_Attributes)

Full attributes of a translation job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (translation_Input)

Source content to translate.

object (translation_Options)

Optional settings controlling translation behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

policy_id
string <uuid> (PolicyId)

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.

object (translation_Result)

Translation output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "event": "translation.completed",
  • "data": {
    • "id": "9a1bc2f3-d405-4678-bcde-f12345678901",
    • "type": "translation-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "source_language": "auto",
        • "formality": "formal",
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {}
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

video-analysis_WebhookPayload

event
required
string
Enum: "video-analysis.progress" "video-analysis.completed" "video-analysis.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the video analysis job.

type
string
Value: "video-analysis-job"

Resource type identifier. Always video-analysis-job.

object (video-analysis_Attributes)

Full attributes of a video analysis job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
object (video-analysis_Input)

Source video and the list of analysis features to run.

object (video-analysis_Options)

Optional settings controlling analysis behaviour.

object (Webhook)

Destination configuration for job lifecycle notifications.

policy_id
string <uuid> (PolicyId)

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.

object (video-analysis_Result)

Video analysis output. Populated once status is completed.

object (Meta)

Metadata envelope shared between client and system.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "event": "video-analysis.completed",
  • "data": {
    • "id": "3e7dc4b2-91f0-4a1e-8c2d-b56789012345",
    • "type": "video-analysis-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {},
      • "options": {
        • "language": "auto",
        • "confidence_threshold": 0.7,
        • "priority": "standard",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "video_metadata": {
          • "duration": 3742.5,
          • "width": 1920,
          • "height": 1080,
          • "frame_rate": 29.97,
          • "format": "mp4",
          • "codec": "h264"
          },
        • "labels": [
          • {
            }
          ],
        • "scenes": [
          • {
            }
          ],
        • "faces": [
          • {
            }
          ],
        • "speech_to_text": [
          • {
            }
          ],
        • "ocr": [
          • {
            }
          ],
        • "content_moderation": {
          • "is_safe": true,
          • "signals": [
            ]
          },
        • "sentiment": {
          • "overall": "positive",
          • "score": 0.62,
          • "instances": [
            ]
          },
        • "topics": [
          • {
            }
          ],
        • "brands": [
          • {
            }
          ],
        • "summary": "A panel discussion on AI safety featuring three researchers. The conversation covers alignment challenges, regulatory proposals, and near-term risk mitigation strategies.\n",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}

llm-task_WebhookPayload

event
required
string
Enum: "llm-task.completed" "llm-task.failed"

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.

object

JSON:API-style data envelope.

id
string <uuid>

Unique identifier for the LLM task job.

type
string
Value: "llm-task-job"

Resource type identifier. Always llm-task-job.

object (llm-task_Attributes)

Full attributes of an LLM task job, combining input, job state, and result.

tenant
string

Slug of the tenant that submitted the job. Derived from the authentication token.

user_id
string

Identifier of the user or client that submitted the job. Derived from the authentication token subject claim.

provider
string

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.

status
string (JobStatus)
Enum: "pending" "processing" "completed" "failed"

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.

progress
integer [ 0 .. 100 ]

Processing progress as a percentage. Only meaningful while status is processing.

object (Error)

Details of a job failure. Only present when status is failed.

object (RoutingInfo)

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.

created_at
string <date-time>

When the job was created.

processed_at
string <date-time>

When the job transitioned from pending to processing. Subtract from created_at to get queue wait time.

completed_at
string <date-time>

When the job reached a terminal state (completed or failed). Subtract from processed_at to get processing duration.

required
Text input (object) or Document input (object) (llm-task_Input)
object (llm-task_Options)

Generation settings for the LLM task.

object (Webhook)

Destination configuration for job lifecycle notifications.

policy_id
string <uuid> (PolicyId)

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.

object (llm-task_Result)

LLM task output. Populated once status is completed.

object (llm-task_Meta)

Metadata envelope for an LLM task job. meta.client is echoed back unchanged from the request. Gateway-internal metadata remains outside the public webhook contract.

object

Arbitrary key-value data provided by the client. Returned unchanged in all responses.

object

Internal metadata added by the gateway. Never exposed in webhook payloads.

{
  • "event": "llm-task.completed",
  • "data": {
    • "id": "c3d2e1f0-a4b5-6789-cdef-012345678901",
    • "type": "llm-task-job",
    • "attributes": {
      • "tenant": "acme-corp",
      • "user_id": "auth0|64a1b2c3d4e5f6789012345",
      • "provider": "twelvelabs",
      • "status": "processing",
      • "progress": 72,
      • "error": {
        • "code": "AUDIO_UNREADABLE",
        • "message": "Could not extract audio from the provided file."
        },
      • "routing": {
        • "provider_id": "eden-ai",
        • "reason": "policy_rule",
        • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
        • "policy_version": 3,
        • "policy_source": "tenant_default",
        • "attempt": 1
        },
      • "created_at": "2024-03-15T10:00:00Z",
      • "processed_at": "2024-03-15T10:00:05Z",
      • "completed_at": "2024-03-15T10:02:30Z",
      • "input": {
        • "type": "text",
        • "text": "Artificial intelligence is transforming industries at an unprecedented pace...",
        • "prompt": "Summarise the following article in three bullet points.",
        • "system_prompt": "You are a helpful assistant. Always respond in plain language suitable for a general audience."
        },
      • "options": {
        • "creativity": "balanced",
        • "include_usage": true
        },
      • "policy_id": "f4a3b2c1-d5e6-7890-abcd-ef1234567890",
      • "result": {
        • "content": "• 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": "completed",
        • "usage": {
          • "input_tokens": 312,
          • "output_tokens": 87,
          • "cost": 0.00088
          }
        }
      },
    • "meta": {
      • "client": { },
      • "system": {
        • "region": "eu-west-1",
        • "worker_id": "wk_789"
        }
      }
    }
}