Developer Docs · Priyo Forge

Quickstart

Send your first chat request in under a minute. Any OpenAI-compatible SDK works — set the base URL to https://api.priyo.ai/v1 and use your Forge key.

curl https://api.priyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "priyo-llama",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain AI in Bangla"}
    ]
  }'

Approved? Find your key on the dashboard. Don't have one yet? Apply for an API key.

Authentication

Every request needs a Authorization: Bearer header. Forge keys start with sk-. Treat them like passwords — never commit them or expose them in client-side code.

Authorization: Bearer sk-priyo-...

Calls that fail authentication return 401 Unauthorized. Revoke or rotate a key any time from your dashboard.

Base URL & SDKs

Forge speaks the OpenAI HTTP spec. Point any OpenAI client at https://api.priyo.ai/v1 and the rest works unchanged. For Claude models, the Anthropic SDK also works — set its base URL to https://api.priyo.ai.

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PRIYO_API_KEY"],
    base_url="https://api.priyo.ai/v1",
)

The Python and Node OpenAI SDK examples below all assume the client is constructed as above.

Chat completions

OpenAI-compatible

Send a list of messages and receive a model reply. Supports streaming, tool calls, JSON-mode, and vision on capable models.

POST/v1/chat/completions

Field	Type	Description
modelrequired	string	Model ID. See available models.
messagesrequired	array	Conversation history as system / user / assistant / tool messages.
stream	boolean	If true, deltas stream back as Server-Sent Events.
temperature	number	0–2. Lower = more deterministic. Defaults to 1.
max_tokens	integer	Cap on response length, in tokens.
tools	array	Function/tool definitions the model can call.
response_format	object	Force structured output, e.g. { type: "json_object" }.

curl https://api.priyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "priyo-llama",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain AI in Bangla"}
    ]
  }'

Example response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1735689600,
  "model": "priyo-llama",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "AI মানে কৃত্রিম বুদ্ধিমত্তা…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 38, "total_tokens": 62 }
}

Streaming

Set stream: true to receive incremental chunks as Server-Sent Events. The stream terminates with a data: [DONE] line.

curl https://api.priyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "priyo-llama",
    "messages": [{"role": "user", "content": "Write a haiku about Dhaka"}],
    "stream": true
  }'

Completions (legacy)

Legacy

The text-completion endpoint for single-prompt use cases. Prefer chat completions for new code.

POST/v1/completions

Field	Type	Description
modelrequired	string	Model ID.
promptrequired	string \| array	Text or array of text to complete.
max_tokens	integer	Maximum tokens to generate.
stream	boolean	Stream tokens as they arrive.

curl https://api.priyo.ai/v1/completions \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "priyo-llama",
    "prompt": "Once upon a time in Dhaka,",
    "max_tokens": 64
  }'

Embeddings

OpenAI-compatible

Convert text into a numeric vector for search, clustering, and retrieval-augmented generation.

POST/v1/embeddings

Field	Type	Description
modelrequired	string	Embedding model ID.
inputrequired	string \| array	Text or array of text to embed.
encoding_format	string	"float" (default) or "base64".
dimensions	integer	Truncate the vector to this many dims (supported models only).

curl https://api.priyo.ai/v1/embeddings \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "priyo-embed",
    "input": "Bangla is a beautiful language."
  }'

Example response

{
  "object": "list",
  "model": "priyo-embed",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0048, ...] }
  ],
  "usage": { "prompt_tokens": 7, "total_tokens": 7 }
}

Models

List the models your key can call. Returns the same shape as OpenAI's /v1/models.

GET/v1/models

curl https://api.priyo.ai/v1/models \
  -H "Authorization: Bearer $PRIYO_API_KEY"

Example response

{
  "object": "list",
  "data": [
    { "id": "priyo-llama", "object": "model", "owned_by": "priyo" },
    { "id": "priyo-qwen", "object": "model", "owned_by": "priyo" },
    { "id": "claude-sonnet-4-6", "object": "model", "owned_by": "anthropic" }
  ]
}

Moderations

Classify whether text contains sexual, hate, violence, self-harm, or other policy-violating content.

POST/v1/moderations

Field	Type	Description
model	string	Moderation model. Defaults to the latest.
inputrequired	string \| array	Text to classify.

curl https://api.priyo.ai/v1/moderations \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-moderation-latest",
    "input": "Sample text to classify."
  }'

Text-to-speech

Audio

Synthesise spoken audio from text. The response body is the raw audio file.

POST/v1/audio/speech

Field	Type	Description
modelrequired	string	TTS model ID.
inputrequired	string	Text to synthesise.
voicerequired	string	Voice ID, e.g. alloy, nova, shimmer.
response_format	string	mp3 (default), opus, aac, flac, wav, pcm.

curl https://api.priyo.ai/v1/audio/speech \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello from Priyo Forge.",
    "voice": "alloy"
  }' \
  --output speech.mp3

Speech-to-text

Audio

Transcribe an audio file into text. Send as multipart/form-data.

POST/v1/audio/transcriptions

Field	Type	Description
filerequired	file	Audio file. mp3, wav, m4a, webm, and more.
modelrequired	string	Transcription model, e.g. whisper-1.
language	string	ISO-639-1 hint (e.g. "bn" for Bangla).
response_format	string	json (default), text, srt, vtt, verbose_json.

curl https://api.priyo.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -F file="@audio.mp3" \
  -F model="whisper-1"

Image generation

Images

Generate an image from a text prompt.

POST/v1/images/generations

Field	Type	Description
modelrequired	string	Image model ID.
promptrequired	string	Description of the image to generate.
size	string	Pixel dimensions, e.g. 1024x1024.
n	integer	Number of images. Defaults to 1.
response_format	string	url (default) or b64_json.

curl https://api.priyo.ai/v1/images/generations \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A street vendor in Dhaka at golden hour, watercolor",
    "size": "1024x1024",
    "n": 1
  }'

Image edits

Images

Edit an existing image (or fill a masked region) using a text prompt. Sent as multipart/form-data.

POST/v1/images/edits

Field	Type	Description
imagerequired	file	PNG to edit. Square images recommended.
promptrequired	string	What the edited image should look like.
mask	file	Optional PNG mask: transparent pixels = areas to edit.
model	string	Image-edit-capable model.
n	integer	Number of variations.

curl https://api.priyo.ai/v1/images/edits \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -F model="gpt-image-1" \
  -F image="@photo.png" \
  -F mask="@mask.png" \
  -F prompt="Add a rickshaw in the background"

Messages (Anthropic format)

Anthropic-compatible

For Claude models, use the native Anthropic Messages format. Drop-in compatible with the official anthropic Python and Node SDKs.

POST/v1/messages

Field	Type	Description
modelrequired	string	Anthropic model ID, e.g. claude-sonnet-4-6.
messagesrequired	array	User/assistant turns. Tool-use blocks supported.
max_tokensrequired	integer	Maximum tokens to generate. Anthropic requires this.
system	string \| array	Top-level system prompt (separate from messages).
stream	boolean	Stream blocks as Server-Sent Events.

curl https://api.priyo.ai/v1/messages \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Summarise Bangla literature in 3 lines."}
    ]
  }'

Responses

OpenAI Responses API

The newer OpenAI Responses API for stateful, agent-style conversations with built-in tool execution and reasoning. Use it with the latest OpenAI SDK.

POST/v1/responses

Field	Type	Description
modelrequired	string	Responses-capable model ID.
inputrequired	string \| array	Prompt string or structured input items.
instructions	string	Top-level system instructions.
tools	array	Function/tool definitions.
stream	boolean	Stream the response as events.

curl https://api.priyo.ai/v1/responses \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "Plan a 3-day Dhaka food tour."
  }'

Rerank

Reorder a set of documents by relevance to a query. Useful as the second stage of a retrieval pipeline.

POST/v1/rerank

Field	Type	Description
modelrequired	string	Rerank model ID.
queryrequired	string	The search query.
documentsrequired	array	Text snippets to score.
top_n	integer	Return only the top N. Defaults to all.

curl https://api.priyo.ai/v1/rerank \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v3.0",
    "query": "best mango variety in Bangladesh",
    "documents": [
      "Himsagar is sweet and aromatic.",
      "The Padma river flows through Bangladesh.",
      "Langra mangoes ripen in early summer."
    ],
    "top_n": 2
  }'

Example response

{
  "id": "rerank-abc123",
  "model": "rerank-english-v3.0",
  "results": [
    { "index": 0, "relevance_score": 0.91 },
    { "index": 2, "relevance_score": 0.78 }
  ]
}

Files

Upload files for batch jobs or other workflows that take a file ID as input.

POST/v1/files

GET/v1/files

GET/v1/files/{file_id}

GET/v1/files/{file_id}/content

DELETE/v1/files/{file_id}

Field	Type	Description
filerequired	file	Uploaded file contents (multipart).
purposerequired	string	What the file is for, e.g. batch.

curl https://api.priyo.ai/v1/files \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -F purpose="batch" \
  -F file="@batch_input.jsonl"

Batches

Submit a JSONL file of requests and pick up the results asynchronously — useful for large offline jobs at lower cost.

POST/v1/batches

GET/v1/batches

GET/v1/batches/{batch_id}

POST/v1/batches/{batch_id}/cancel

Field	Type	Description
input_file_idrequired	string	ID of a JSONL file uploaded with purpose=batch.
endpointrequired	string	Endpoint the batch targets, e.g. /v1/chat/completions.
completion_windowrequired	string	Currently only "24h" is supported.
metadata	object	Arbitrary key-value labels to attach.

curl https://api.priyo.ai/v1/batches \
  -H "Authorization: Bearer $PRIYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

Errors

Errors follow the OpenAI shape — your existing error handling works unchanged.

Example response

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Status	Meaning	What to do
400	Bad request — invalid params or body.	Check the request shape against this page.
401	Missing or invalid API key.	Confirm the Authorization header and that the key is still active.
403	Key is valid but lacks access to the model.	Pick a model your tier can call.
404	Unknown model or endpoint.	List models via /v1/models to verify the ID.
429	Rate or quota limit hit.	Back off and retry with exponential delay.
500	Upstream provider failure.	Retry; if it persists, ping the community.

Need help? Reach out via the builder community.

Build with the Priyo Forge API

Streaming