Skip to main content

๐Ÿ“Ÿ Requests

Request formatโ€‹

The Muse API is accessed through POST HTML requests, from the tool of your choice (curl, requests, ...).

The example request below queries the โœ๏ธ Create endpoint of the lyra-fr model, with the prompt Once upon a time, and asks for a completion of length 25 tokens ("n_tokens": 25).

curl -X 'POST' \
'https://api.lighton.ai/muse/v1/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'X-Model: lyra-fr' \
-d '{"text": "Il รฉtait une fois", "params": {"n_tokens": 25}}'

Requests should follow this format:

  • Endpoint/primitive URL: https://api.lighton.ai/muse/v1/{endpoint} (e.g. create, select, etc.).
  • JSON Payload Header: the API works with JSON payloads only, so you should set Content-Type: application/json and Accept: application/json in your requests.
  • Authentication Header: X-API-KEY: {YOUR_API_KEY}, see ๐Ÿ”‘ Authentication for more details.
  • Model Header: which model you want to query, see ๐Ÿค– Models for availability across languages.
  • JSON payload for the request: the request and its parameters should be specified in JSON format. All endpoints usually take the main text(s) first, and then the extra parameters. See the specific documentation of each primitive for details.

As an example, the request above will generate a response similar to the following (see ๐Ÿ’ฌ Responses for more information).

Example response (JSON)
{
"request_id": "734e8d5a-a186-4d14-b2e4-be26f7fee6dc",
"outputs": [
[
{
"input_text": "Il รฉtait une fois",
"completions": [
{
"output_text": ", un pays oรน il faisait toujours beau.\nLes gens y vivaient heureux et en sรฉcuritรฉ. Ils avaient de l'argent",
"score": {
"logprob": -42.8507080078125,
"normalized_logprob": -1.7140283203125,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 29,
"tokens_input": 4,
"tokens_generated": 25,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
}
]
],
"costs": {
"lyra-fr@default": {
"total_tokens_used": 29,
"total_tokens_input": 4,
"total_tokens_generated": 25,
"batch_size": 1
}
}
}

Batching requestsโ€‹

If you are planning to process data in bulk, and/or to make many independent API calls, you may benefit from the Muse API ability to batch requests to the same endpoint and model. Batching enables lower latency and faster and simplified processing.

The API supports both batching with the same parameters and with different parameters.

Simple batching: with the same parametersโ€‹

Batching with the same parameters is as simple as providing a list of strings to the main text parameter. For example, let us consider the following

Batched request payload (JSON)
{
"text": ["Once upon a time", "Mars is a planet"],
"params": { "n_tokens": 25 }
}

When used with โœ๏ธ Create, this will return completions of 25 tokens for both "Once upon a time" and "Mars is a planet". The outputs list will contain one entry for each item in text.

Batched response (JSON)
{
"request_id": "c67fbd27-7bbf-4895-816a-9c5b6b90eafb",
"outputs": [
[
{
"input_text": "Once upon a time",
"completions": [
{
"output_text": "... in the west ยป (version anglaise, interprรฉtรฉe par The Beach Boys). Il s'agit d'un re",
"score": {
"logprob": -41.53728151321411,
"normalized_logprob": -1.6614912605285646,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 31,
"tokens_input": 6,
"tokens_generated": 25,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
},
{
"input_text": "Mars is a planet",
"completions": [
{
"output_text": " of great importance for the planet and the universe, it is also an important element for humanity. The",
"score": {
"logprob": -40.30290484428406,
"normalized_logprob": -1.6121161937713624,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 30,
"tokens_input": 5,
"tokens_generated": 25,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
}
]
],
"costs": {
"lyra-fr@default": {
"total_tokens_used": 61,
"total_tokens_input": 11,
"total_tokens_generated": 50,
"batch_size": 2
}
}
}

Advanced batching: with different parametersโ€‹

The API also supports batching requests with different parameters. To do this, your input payload should now be a list of dictionaries, each dictionary representing a request. It is possible to mix this with simple batching, as demonstrated below:

Advanced batch request payload (JSON)
[
{
"text": ["Once upon a time", "Mars is a planet"],
"params": { "mode": "greedy", "n_tokens": 10 }
},
{
"text": ["Once upon a time", "Mars is a planet"],
"params": { "mode": "nucleus", "n_tokens": 25 }
}
]

When used with โœ๏ธ Create, this will return two group of completions of 25 tokens for both "Once upon a time" and "Mars is a planet", one group with greedy sampling, and the other with nucleus sampling. The outputs list will contain one list for each parameters configuration, each containing one entry per item in text.

Advanced batched response (JSON)
{
"request_id": "b2a6c856-7a4d-4b49-90f1-2a5c09e99a91",
"outputs": [
[
{
"input_text": "Once upon a time",
"completions": [
{
"output_text": " in Hollywood, de Quentin Tarantino, avec",
"score": {
"logprob": -10.150981426239014,
"normalized_logprob": -1.0150981426239014,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 16,
"tokens_input": 6,
"tokens_generated": 10,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
},
{
"input_text": "Mars is a planet",
"completions": [
{
"output_text": "ary habitable zone, which is the most favorable",
"score": {
"logprob": -20.3642578125,
"normalized_logprob": -2.03642578125,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 15,
"tokens_input": 5,
"tokens_generated": 10,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
}
],
[
{
"input_text": "Once upon a time",
"completions": [
{
"output_text": " in an... au foyer\nCult; Pop\nJohnny Cash\nThe Raconteurs\nBob Dylan\nMek",
"score": {
"logprob": -87.58248901367188,
"normalized_logprob": -3.503299560546875,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 31,
"tokens_input": 6,
"tokens_generated": 25,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
},
{
"input_text": "Mars is a planet",
"completions": [
{
"output_text": " like the Sun, the Sun is like Mars and the moon is like the Moon ยป โ€“ James Cook. Elle a une",
"score": {
"logprob": -54.189552307128906,
"normalized_logprob": -2.1675820922851563,
"token_logprobs": null
},
"execution_metadata": {
"cost": {
"tokens_used": 30,
"tokens_input": 5,
"tokens_generated": 25,
"cost_type": "lyra-fr@default",
"batch_size": 1
},
"finish_reason": "length"
}
}
]
}
]
],
"costs": {
"lyra-fr@default": {
"total_tokens_used": 92,
"total_tokens_input": 22,
"total_tokens_generated": 70,
"batch_size": 4
}
}
}