Quickstart

Djelia speaks the OpenAI protocol, so you use the OpenAI SDK for your language. There is no Djelia library to install.

1. Get a key

Create one in the Djelia Console and put it in your environment:

export DJELIA_API_KEY="your-api-key"

2. Install the OpenAI SDK

Python

pip install openai

JavaScript

npm install openai

Go

go get github.com/openai/openai-go/v3

curl

Nothing to install.

3. Make Bambara speech

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DJELIA_API_KEY"],
    base_url="https://api.djelia.cloud/openai/v1",
)

speech = client.audio.speech.create(
    model="jifili-1",
    input="Aw ni ce, i ka kene wa?",
    voice="moussa",
)
speech.write_to_file("hello.mp3")

JavaScript

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  apiKey: process.env.DJELIA_API_KEY,
  baseURL: "https://api.djelia.cloud/openai/v1",
});

const speech = await client.audio.speech.create({
  model: "jifili-1",
  input: "Aw ni ce, i ka kene wa?",
  voice: "moussa",
});

fs.writeFileSync("hello.mp3", Buffer.from(await speech.arrayBuffer()));

Go

package main

import (
	"context"
	"io"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("DJELIA_API_KEY")),
		option.WithBaseURL("https://api.djelia.cloud/openai/v1"),
	)

	res, err := client.Audio.Speech.New(context.TODO(), openai.AudioSpeechNewParams{
		Model: "jifili-1",
		Input: "Aw ni ce, i ka kene wa?",
		Voice: openai.AudioSpeechNewParamsVoiceUnion{OfString: openai.String("moussa")},
	})
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := os.Create("hello.mp3")
	defer out.Close()
	io.Copy(out, res.Body)
}

curl

curl https://api.djelia.cloud/openai/v1/audio/speech \
  -H "Authorization: Bearer $DJELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jifili-1",
    "input": "Aw ni ce, i ka kene wa?",
    "voice": "moussa"
  }' \
  --output hello.mp3

You now have an mp3 of Bambara speech. Aw ni ce, i ka kene wa? is "Hello, how are you?"

4. Read it back

Python

transcript = client.audio.transcriptions.create(
    file=open("hello.mp3", "rb"),
    model="sunjata-1",
)
print(transcript.text)

JavaScript

const transcript = await client.audio.transcriptions.create({
  file: fs.createReadStream("hello.mp3"),
  model: "sunjata-1",
});

console.log(transcript.text);

Go

audio, _ := os.Open("hello.mp3")
defer audio.Close()

transcript, err := client.Audio.Transcriptions.New(context.TODO(),
	openai.AudioTranscriptionNewParams{
		File:  audio,
		Model: "sunjata-1",
	})
if err != nil {
	panic(err)
}
fmt.Println(transcript.Text)

curl

curl https://api.djelia.cloud/openai/v1/audio/transcriptions \
  -H "Authorization: Bearer $DJELIA_API_KEY" \
  -F file=@hello.mp3 \
  -F model=sunjata-1

Aw ni ce, i ka kɛnɛ wa?

5. Translate text

Text translation is addressed as a chat model. The language pair is a Djelia extension, because a chat request has nowhere else to carry it.

Python

completion = client.chat.completions.create(
    model="banjugu-1",
    messages=[{"role": "user", "content": "Bonjour, comment allez-vous ?"}],
    extra_body={"djelia": {"source_language": "fra_Latn", "target_language": "bam_Latn"}},
)
print(completion.choices[0].message.content)

JavaScript

const completion = await client.chat.completions.create({
  model: "banjugu-1",
  messages: [{ role: "user", content: "Bonjour, comment allez-vous ?" }],
  ...{ djelia: { source_language: "fra_Latn", target_language: "bam_Latn" } },
});

console.log(completion.choices[0].message.content);

Go

chat, err := client.Chat.Completions.New(context.TODO(),
	openai.ChatCompletionNewParams{
		Model: "banjugu-1",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Bonjour, comment allez-vous ?"),
		},
	},
	option.WithJSONSet("djelia", map[string]string{
		"source_language": "fra_Latn",
		"target_language": "bam_Latn",
	}),
)
if err != nil {
	panic(err)
}
fmt.Println(chat.Choices[0].Message.Content)

curl

curl https://api.djelia.cloud/openai/v1/chat/completions \
  -H "Authorization: Bearer $DJELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "banjugu-1",
    "messages": [{"role": "user", "content": "Bonjour, comment allez-vous ?"}],
    "djelia": {"source_language": "fra_Latn", "target_language": "bam_Latn"}
  }'

Nbá, í ni sɔ̀gɔmà ?

Next

• Djelia extensions for prompt-steerable voices, telephony formats and the language pair
• Models for what each model is good at, and the OpenAI aliases
• API reference for every endpoint and field
• Errors for the envelope and what each status means