API Reference

The OpenTyphoon.ai API is designed to be compatible with OpenAI’s API, making it easy to integrate if you’re already familiar with OpenAI. This reference covers all available endpoints, required and optional parameters, and example response formats.

Authentication

All API requests require authentication using your API key. Include your API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Base URL

All API requests should be made to:

https://api.opentyphoon.ai/v1

Endpoints

Chat Completions

Generate a completion for a chat conversation.

Endpoint: POST /v1/chat/completions

Request Body Parameters

Parameter	Type	Required	Description
model	string	Yes	ID of the model to use (e.g., “typhoon-v2-70b-instruct”).
messages	array	Yes	Array of message objects representing the conversation history.
max_tokens	integer	No	Maximum number of tokens to generate. Default is 150, maximum is 8192 tokens shared between prompt and completion.
temperature	float	No	Sampling temperature between 0 and 2. Higher values like 0.8 will make output more random, while lower values like 0.2 make it more focused and deterministic. Default is 0.7.
top_p	float	No	Alternative to sampling with temperature, called nucleus sampling. We recommend altering this or temperature but not both. Default is 1.
n	integer	No	How many chat completion choices to generate for each input message. Default is 1.
stream	boolean	No	If set to true, partial message deltas will be sent as data-only server-sent events. Default is false.
stop	string or array	No	Up to 4 sequences where the API will stop generating further tokens.
presence_penalty	float	No	Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far. Default is 0.
frequency_penalty	float	No	Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far. Default is 0.
repetition_penalty	float	No	Number between 1.0 and 2.0. Penalizes repeated tokens. Default is 1.0. We suggest 1.05 for good results.
user	string	No	A unique identifier representing your end-user, which can help monitoring and detecting abuse.

Messages Array Format

Each message in the messages array should have a role and content:

{
  "role": "system" | "user" | "assistant",
  "content": "The message content"
}

system: Sets behavior of the assistant
user: The user’s messages
assistant: Messages from the assistant

Example Request

curl --location 'https://api.opentyphoon.ai/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "model": "typhoon-v2-70b-instruct",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant that translates English to Thai."
      },
      {
        "role": "user",
        "content": "Translate the following: Hello, how are you?"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

import openai

client = openai.OpenAI(
    api_key="<YOUR_API_KEY>",
    base_url="https://api.opentyphoon.ai/v1"
)

response = client.chat.completions.create(
    model="typhoon-v2-70b-instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that translates English to Thai."},
        {"role": "user", "content": "Translate the following: Hello, how are you?"}
    ],
    temperature=0.7,
    max_tokens=256
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<YOUR_API_KEY>',
  baseURL: 'https://api.opentyphoon.ai/v1',
});

async function translate() {
  const response = await openai.chat.completions.create({
    model: 'typhoon-v2-70b-instruct',
    messages: [
      {
        role: 'system',
        content: 'You are a helpful assistant that translates English to Thai.'
      },
      {
        role: 'user',
        content: 'Translate the following: Hello, how are you?'
      }
    ],
    temperature: 0.7,
    max_tokens: 256
  });

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

translate();

Response Format

{
  "id": "cmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "typhoon-v2-70b-instruct",
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 12,
    "total_tokens": 37
  },
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "สวัสดี คุณสบายดีไหม?"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ]
}

Streaming Response

When stream is set to true, the API will send partial responses as they are generated, with each chunk containing the newly generated content:

data: {"id":"cmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"typhoon-v2-70b-instruct","choices":[{"index":0,"delta":{"role":"assistant","content":"สวัสดี"},"finish_reason":null}]}

data: {"id":"cmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"typhoon-v2-70b-instruct","choices":[{"index":0,"delta":{"content":" คุณ"},"finish_reason":null}]}

data: {"id":"cmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"typhoon-v2-70b-instruct","choices":[{"index":0,"delta":{"content":"สบายดี"},"finish_reason":null}]}

data: {"id":"cmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"typhoon-v2-70b-instruct","choices":[{"index":0,"delta":{"content":"ไหม?"},"finish_reason":null}]}

data: {"id":"cmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"typhoon-v2-70b-instruct","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Python
JavaScript

from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_API_KEY>",
    base_url="https://api.opentyphoon.ai/v1"
)

stream = client.chat.completions.create(
    model="typhoon-v2-70b-instruct",
    messages=[
        {"role": "user", "content": "เล่าเรื่องตำนานไทยสั้นๆ"}
    ],
    stream=True
)

# Process the streaming response
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()  # Add a newline at the end

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<YOUR_API_KEY>',
  baseURL: 'https://api.opentyphoon.ai/v1',
});

async function streamCompletion() {
  const stream = await openai.chat.completions.create({
    model: 'typhoon-v2-70b-instruct',
    messages: [
      { role: 'user', content: 'เล่าเรื่องตำนานไทยสั้นๆ' }
    ],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
  console.log(); // Add a newline at the end
}

streamCompletion();

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request.

Status Code	Description
200	OK - The request was successful
400	Bad Request - The request was malformed or invalid
401	Unauthorized - Invalid API key
403	Forbidden - The API key doesn’t have permission to perform the request
404	Not Found - The requested resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - An error occurred on the server

Error Response Format

{
  "error": {
    "message": "Description of the error",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}