API
fetch-request
await fetch("https://api.oneword.domains/gpt/generate", {
"method": "POST",
"headers": {
"Authorization": "Bearer <TOKEN>",
"Content-Type": "application/json"
},
"body": JSON.stringify({
// Request parameters
})
})Request parameters
These are the request parameters that should be included in the body of the request. While none of the request parameters are required, they are useful for customizing the generated output.
If left undefined, the default values for each parameter will be used.
| Parameter | Type | Description | Default |
|---|---|---|---|
type | string | The type of name to generate. Refer to the Name Types section for all the possible values. | "random" |
context | string | Added context about the nature of the business or product to generate the name for. E.g. "An AI-powered personal finance assistant that optimizes your spending, saving, and investing habits." | undefined |
minLength | number | The minimum length of the generated name. | 7 |
maxLength | number | The maximum length of the generated name. | 12 |
word | string | A word to be included in the generated name. | undefined |
position | string | The position of the word to be included in the generated name (only used when word is defined). Possible values: "prefix", "suffix", "anywhere". | "prefix" |
tld | string | The top-level domain to be appended to the generated name. | "com" |
domains | string[] | A list of previously-generated domains (to avoid duplicates). | [] |
Name Types
The type parameter can be set to any of the following values:
| Value | Description | Examples |
|---|---|---|
"portmanteau" | Names that are a creative blend of two words | "Pinterest", "Instagram", "FedEx" |
"combination" | Names that are two-word combinations | "Facebook", "YouTube", "OpenDoor" |
"brandable" | Names that don't have a specific meaning but are memorable | "Google", "Rolex", "Ikea", "Nike", "Quora" |
"nonenglish" | Names that are non-English words | "Toyota", "Audi", "Nissan" |
"alternate" | Names that are misspellings of existing words | "Lyft", "Fiverr", "Dribbble" |
"random" | Let the AI do its thing ✨ | "TikTok", "Airbnb", "Netflix" |
Response
The response from the API is a ReadableStream (opens in a new tab) of stringified JSON objects.
Response
{ "domain": "openflicker.com", "available": true } { "domain": "openlyric.com", "available": false }You have the option to stream the response directly to the client as it is generated, or you can wait for the entire response to be received before sending it to the client. For a better user experience, we highly recommend the former approach.
Method 1: Streaming the response (Recommended)
You can stream the response directly to the client as it is generated by using the getReader() method on the response object. Here's an example:
App.js
const [domains, setDomains] = useState([]);
const [generating, setGenerating] = useState(false);
const generateDomain = async () => {
setDomains([]);
setGenerating(true);
const response = await fetch("https://api.oneword.domains/gpt/generate", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "portmanteau",
word: "open",
position: "prefix",
}),
});
// This data is a ReadableStream
const data = response.body;
if (!data) {
return;
}
const reader = data.getReader();
const decoder = new TextDecoder();
let done = false;
let tempState = "";
while (!done) {
const { value, done: doneReading } = await reader.read();
done = doneReading;
let chunkValue = decoder.decode(value);
// Here, we are defining a temporary state because the response stream
// can get fragmented due to the behavior/distance between the client
// and the server. So, we need to keep track of the previous chunk
// and append it to the current chunk to make sure we have a complete
// JSON string.
if (tempState) {
chunkValue = tempState + chunkValue;
tempState = "";
}
// Here, we match the complete JSON string and extract it from the chunk
// and save the remaining string in the tempState variable.
const match = chunkValue.match(/\{(.*?)\}/);
if (match) {
tempState = chunkValue.replace(match[0], "");
chunkValue = match[0];
}
try {
const { domain, available } = JSON.parse(chunkValue);
setDomains((prev) => [...prev, { domain, available }]);
} catch (e) {
// if the JSON.parse method fails, it means that the chunkValue
// is not a complete JSON string and the stream is fragmented.
// So, we save the chunkValue in the tempState variable and
// append it to the next chunk.
tempState = chunkValue;
}
}
setGenerating(false);
};You can see this example in action in the demo below:
Method 2: Awaiting the response
If you really want to wait for the entire response to be received before sending it to the client, you can do so with the following code:
App.js
const [domains, setDomains] = useState([]);
const [generating, setGenerating] = useState(false);
const generateDomain = async () => {
setDomains([]);
setGenerating(true);
const response = await fetch("https://api.oneword.domains/gpt/generate", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "portmanteau",
word: "open",
position: "prefix",
}),
}).then((res) => res.text());
const domainsArray = response
.split("}")
.filter((str) => str.trim() !== "")
.map((str) => str.trim() + "}")
.map((objectString) => JSON.parse(objectString));
setDomains(domainsArray);
setGenerating(false);
};You can see this example in action in the demo below: