Create - Text2API

The POST /translations endpoint processes a human-written text and transforms it into a structured JSON object based on the schema defined in the request body. This allows users to specify the desired format, structure, and constraints of the output JSON.

You'll need to provide a valid API Key to test this request. Visit "How to Get Your Test API Key" to get one!

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

User-Id

string

required

A unique identifier for the end user of this translation. Using the same User-Id in multiple requests will use the same thread and be a little faster than using a different value (and creating a new thred from scratch each time).

Example:

user_2

Body Params application/json

translation_type

string

required

The type of translation you want to create, for now only "object" is supported

Default:

object

target_object

array[object (ObjectField) {8}]

required

The schema of the object you want as an output

string

required

The name of the field inside the output object

type

string

required

The type for the field value. Valid types are string, date, number, boolean, array, object

description

string

optional

A brief description of the field. This will improve AI agent accuracy but long descriptions will increase your request cost

allowed_values

array[string]

optional

Array of the optional values this field can have

format

string

optional

If the field needs to be in a specific format, like a date, you can specify the format here

fields

object (ObjectField)

optional

If the field type is "object", here you can define it's fields

depends_on

string

optional

If this field depends on another field in the object, you can specify it's name here

dependent_allowed_values

array[object (DependentAllowedValues) {2}]

optional

If this field has a dependency, here you can define an array of the potential values that field might have, and the allowed values for this field for every case

input_text

string

required

The human-written text you want to translate into a JSON object

Example:

50 usd, amazon gift card for my nephew

lang

string

optional

The desired output language

Example

{
  "translation_type": "object",
  "input_text": "150 USD in groceries at walmart",
  "target_object": {
    "fields": [
      {
        "allowed_values": [],
        "name": "description",
        "type": "string"
      },
      {
        "type": "number",
        "allowed_values": [],
        "name": "amount"
      },
      {
        "type": "string",
        "allowed_values": [
          "usd",
          "eur",
          "mxn"
        ],
        "name": "currency"
      },
      {
        "type": "string",
        "allowed_values": [
          "guilt-free",
          "fixed-costs",
          "savings",
          "investments"
        ],
        "name": "category"
      },
      {
        "type": "string",
        "depends_on": "category",
        "dependent_allowed_values": [
          {
            "value": "guilt-free",
            "allowed_values": [
              "clothes",
              "entertainment",
              "eating_out"
            ]
          },
          {
            "value": "fixed-costs",
            "allowed_values": [
              "food",
              "rent",
              "internet",
              "phone"
            ]
          },
          {
            "value": "savings",
            "allowed_values": [
              "emergency",
              "travel",
              "gifts"
            ]
          },
          {
            "value": "investments",
            "allowed_values": [
              "stocks",
              "bonds",
              "crypto"
            ]
          }
        ],
        "name": "sub_category"
      },
      {
        "type": "date",
        "format": "ISO-8601",
        "description": "Date when the expense was made",
        "name": "created_at"
      }
    ]
  },
  "lang": "english"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.seniorgo.io/v1/translations' \
--header 'User-Id: user_2' \
--header 'Content-Type: application/json' \
--data-raw '{
  "translation_type": "object",
  "input_text": "150 USD in groceries at walmart",
  "target_object": {
    "fields": [
      {
        "allowed_values": [],
        "name": "description",
        "type": "string"
      },
      {
        "type": "number",
        "allowed_values": [],
        "name": "amount"
      },
      {
        "type": "string",
        "allowed_values": [
          "usd",
          "eur",
          "mxn"
        ],
        "name": "currency"
      },
      {
        "type": "string",
        "allowed_values": [
          "guilt-free",
          "fixed-costs",
          "savings",
          "investments"
        ],
        "name": "category"
      },
      {
        "type": "string",
        "depends_on": "category",
        "dependent_allowed_values": [
          {
            "value": "guilt-free",
            "allowed_values": [
              "clothes",
              "entertainment",
              "eating_out"
            ]
          },
          {
            "value": "fixed-costs",
            "allowed_values": [
              "food",
              "rent",
              "internet",
              "phone"
            ]
          },
          {
            "value": "savings",
            "allowed_values": [
              "emergency",
              "travel",
              "gifts"
            ]
          },
          {
            "value": "investments",
            "allowed_values": [
              "stocks",
              "bonds",
              "crypto"
            ]
          }
        ],
        "name": "sub_category"
      },
      {
        "type": "date",
        "format": "ISO-8601",
        "description": "Date when the expense was made",
        "name": "created_at"
      }
    ]
  },
  "lang": "english"
}'

Responses

🟢200Successful Response

application/json

Body

string

optional

The unique identifier generated for this request

mapped_object

object

required

A JSON object with the schema you defined in your request

Example

{
    "id": "abc",
    "mapped_object": {
        "amount": 150,
        "category": "fixed-costs",
        "created_at": "2025-01-16",
        "currency": "usd",
        "description": "150 USD in groceries at walmart",
        "sub_category": "food"
    }
}

🟠400Invalid Request