Embed documents

Perform embedding on a Telnyx Storage Bucket using the a embedding model. The current supported file types are:

PDF
HTML
txt/unstructured text files
json
csv
audio / video (mp3, mp4, mpeg, mpga, m4a, wav, or webm ) - Max of 100mb file size.

Any files not matching the above types will be attempted to be embedded as unstructured text.

This process can be slow, so it runs in the background and the user can check the status of the task using the endpoint /ai/embeddings/{task_id}.

Important Note: When you update documents in a Telnyx Storage bucket, their associated embeddings are automatically kept up to date. If you add or update a file, it is automatically embedded. If you delete a file, the embeddings are deleted for that particular file.

You can also specify a custom loader param. Currently the only supported loader value is intercom which loads Intercom article jsons as specified by the Intercom article API This loader will split each article into paragraphs and save additional parameters relevant to Intercom docs, such as article_url and heading. These values will be returned by the /v2/ai/embeddings/similarity-search endpoint in the loader_metadata field.

POST

embeddings

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const embeddingResponse = await client.ai.embeddings.create({ bucket_name: 'bucket_name' });

console.log(embeddingResponse.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
embedding_response = client.ai.embeddings.create(
    bucket_name="bucket_name",
)
print(embedding_response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	embeddingResponse, err := client.AI.Embeddings.New(context.TODO(), telnyx.AIEmbeddingNewParams{
		BucketName: "bucket_name",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", embeddingResponse.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.ai.embeddings.EmbeddingCreateParams;
import com.telnyx.sdk.models.ai.embeddings.EmbeddingResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        EmbeddingCreateParams params = EmbeddingCreateParams.builder()
            .bucketName("bucket_name")
            .build();
        EmbeddingResponse embeddingResponse = client.ai().embeddings().create(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $embeddingResponse = $client->ai->embeddings->create(
    bucketName: 'bucket_name',
    documentChunkOverlapSize: 0,
    documentChunkSize: 0,
    embeddingModel: 'thenlper/gte-large',
    loader: 'default',
  );

  var_dump($embeddingResponse);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/ai/embeddings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bucket_name": "Bucket Name",
  "document_chunk_size": 1024,
  "document_chunk_overlap_size": 512,
  "embedding_model": "thenlper/gte-large",
  "loader": "default"
}
'

{
  "data": {
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task_name": "Task Name",
    "status": "Status",
    "created_at": "Created At",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10036",
      "title": "Resource is being processed",
      "detail": "A request with this Idempotency-Key is already being processed.",
      "source": {
        "pointer": "/header/Idempotency-Key"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_-]{1,255}$

Body

application/json

bucket_name

string

required

document_chunk_size

integer

default:1024

document_chunk_overlap_size

integer

default:512

embedding_model

enum<string>

default:thenlper/gte-large

Supported models to vectorize and embed documents.

Available options:

thenlper/gte-large,

intfloat/multilingual-e5-large

loader

enum<string>

default:default

Supported types of custom document loaders for embeddings.

Available options:

default,

intercom

Response

Successful Response

data

object

required

Show child attributes

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const embeddingResponse = await client.ai.embeddings.create({ bucket_name: 'bucket_name' });

console.log(embeddingResponse.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
embedding_response = client.ai.embeddings.create(
    bucket_name="bucket_name",
)
print(embedding_response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	embeddingResponse, err := client.AI.Embeddings.New(context.TODO(), telnyx.AIEmbeddingNewParams{
		BucketName: "bucket_name",
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", embeddingResponse.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.ai.embeddings.EmbeddingCreateParams;
import com.telnyx.sdk.models.ai.embeddings.EmbeddingResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        EmbeddingCreateParams params = EmbeddingCreateParams.builder()
            .bucketName("bucket_name")
            .build();
        EmbeddingResponse embeddingResponse = client.ai().embeddings().create(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $embeddingResponse = $client->ai->embeddings->create(
    bucketName: 'bucket_name',
    documentChunkOverlapSize: 0,
    documentChunkSize: 0,
    embeddingModel: 'thenlper/gte-large',
    loader: 'default',
  );

  var_dump($embeddingResponse);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/ai/embeddings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bucket_name": "Bucket Name",
  "document_chunk_size": 1024,
  "document_chunk_overlap_size": 512,
  "embedding_model": "thenlper/gte-large",
  "loader": "default"
}
'

{
  "data": {
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task_name": "Task Name",
    "status": "Status",
    "created_at": "Created At",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10036",
      "title": "Resource is being processed",
      "detail": "A request with this Idempotency-Key is already being processed.",
      "source": {
        "pointer": "/header/Idempotency-Key"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Embedding

Bucket

OpenAI-compatible

API Reference

For AI Agents

Embed documents

Authorizations

Headers

Body

Response