Data Foundry Data Foundry Documentation

Using the OpenAI API in scripts

This page explains how to use the OpenAI API in Data Foundry.

NOTE: The use of this API is controlled by Data Foundry and at the moment free. We will monitor the usage of the API and also log all prompts that are submitted for quality assurance and debugging purposes. If you suspect that your API key has somehow leaked, generate a new one (which invalidates the old one) and contact us for help. By using the API you acknowledge these terms.

Step-by-step guide

Create a new project or use an existing project; important: you need to be the owner of the project
Open the project edit page (pen icon on main project page)
Scroll down to the API Access section
Read information carefully and click the button to generate a new API key
Copy the API key; it should look like df-AHFJed65hg09sdv098asdvadv98
Add a new script or open an existing script in the project
Try a few of the examples below, using the copied API key for <API-KEY>

Completion example

A completion needs a prompt and the API will return a completion of this prompt. Read more about text completion in the official API docs. You will also find useful tips and tricks how to craft a good prompt.

Let's try a first example. We want to generate a tagline for a flower shop.

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "completion",
  "prompt": "Write a tagline for a flower shop."
})
DF.print(result)

The output is below:

{"text":"\n\nFlowers for a global audience.","finishReason":"stop","cost":18}

By taking this output object apart, we get the resulting text "Flowers for a global audience." (Note that the output can differ when you try it.), finishReason which gives you an idea about why GPT stopped generating tokens ("stop" is usually good, meaning that GPT's output was not cut off by a token limit), and the rough cost of the operation.

You can get just the text by using

DF.print(result.text)

The example above uses the cheapest, fastest GPT model, which is called ada. Let's try a more expensive model:

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "completion",
  "model": "curie",
  "prompt": "Write a tagline for a flower shop."
})
DF.print(result)

The output text now is: "We offer the best in fresh flowers, plants, gifts and delivery!" Note that the output can differ when you try it. Also the cost is slightly higher. To read more about the different GPT models available, continue here

Another example is to generate text like an explanation:

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "completion",
  "model": "curie",
  "prompt": "Explain the difference between apples, oranges and pears for a primary school kid."
})
DF.print(result)

Result:

{"text":"\n\nApple, orange and pear are fruits. Apples are the most common type of fruit eaten whole. O oranges are the most common type of fruit eaten peeled and sectioned. Pears are the most common type of fruit eaten peeled and sectioned.","finishReason":"stop","cost":69}

Weird? Let's try again:

{"text":"\n\nApples are red and have a crispy skin. Oranges are orange and have a juicy skin. Pears are green and have a squishy skin.","finishReason":"stop","cost":50}

We can change the prompt: "Explain the difference between apples, oranges and pears to a six year old child."

{"text":"\n\nApples are round with a smooth skin and are bright red or green. Oranges are oval with a bumpy skin and areusually orange but can also be yellow or brown. Pears are also oval but are usually smooth, can be green or red and are a bit juicier than apples.","finishReason":"stop","cost":81}

Or use the davinci model which should give us the best output:

{"text":"\n\nApples are round and red, with a slightly sour taste. They come in many different colors, like green and yellow. Oranges are round and sweet, with a juicy inside and a thick peel. Pears are small, narrow, and pear-shaped, and have a soft, juicy texture. They taste sweet and slightly tart.","finishReason":"stop","cost":88}

Moderation example

THe moderation API endpoint can be used to identify content that violates common policies and to filter it.

The first example should result in a "flagged" moderation result:

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "moderation",
  "prompt": "testy banana"
})
DF.print(result)

The second example should result in a "non-flagged" moderation result:

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "moderation",
  "prompt": "testy kiwi"
})
DF.print(result)

Chat example

THe chat completion API endpoint can be used to generate a new reply to an existing chat, i.e., a list of prior messages. The main difference to the "normal" completion is that the messages are provided in a list and each message has a role (who is speaking) and content (what are they saying).

The following example shows a simple continuation of a chat:

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "chat",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Who won the world series in 2020?" },
    { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." },
    { "role": "user", "content": "Where was it played?" }
  ]
})
DF.print(result)

Note that chat completions are running with the most advanced GPT model and they are still ten times cheaper than using the best davinci GPT model.

API concepts

Models

The Data Foundry API offers different models, in ascending order of cost:

Ada (4 💸) -> ada, Babbage (5 💸) -> babbage, Curie (20 💸) -> curie, Davinci (200 💸) -> davinci, and 🔥 GPT-4 (800 💸) -> gpt-4 🔥

The models have different capabilities. Check out the reference. When running an API request, you can check your used and max credit on the project edit page (where you created the API key). If you have insufficient credits, contact us to get more.

Recommendation: Chat completions (20 💸) are cheaper than GPT Davinci, and often higher quality (see example above).

Credits

You can request the current number of available credits for requests on this API. Requests need a df-... API key which needs to match the project of the script.

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "credits"
})

Example output:

{"tokensUsed":1108,"tokensMax":2000}

Note: When there are more credits added to an API key, the tokensMax value will increase. tokensUsed will monotonically increase with use.

Using your own API key

Instead of using the Data Foundry API key, you can also use your own OpenAI API key. This can be obtained from the OpenAI platform (register first, then generate key). You can use this key in all requests as shown above in the api_token field.

API reference

There are more options available than explained above. We generally follow the OpenAI parameter names.

All DF API requests follow the structure, with openai-gpt as the only currently available API:

let result = DF.api("openai-gpt", {
  "api_token": "<API-KEY>", 
  "task": "completion|moderation",
  "prompt": "...",
  ... more parameters...
})

Completion requests

You can use the following parameters: prompt, temperature, presence_penalty, frequency_penalty

Details in the official reference

Moderation requests

You can use the following parameter: input --> prompt

Details in the official reference