Hamiran API

OpenAI-compatible AI API

The Hamiran API provides OpenAI-compatible endpoints for chat completions. You can use any OpenAI SDK or HTTP client to interact with our API — just change the base URL and API key.

Quick Start

Set your base URL to https://ham-iran.ir/v1 and use your API key from the dashboard. That's it!

Authentication

The Hamiran API uses API keys for authentication. You can create and manage your API keys from the chat dashboard under API Keys in the profile menu.

All API requests must include your API key in the Authorization header.

Header

Authorization: Bearer hm-your-api-key

Keep your keys safe

Never share your API key or commit it to version control. Use environment variables to store it securely.

Rate Limits

Rate limits are applied per API key. If you exceed the limit, the API will return a 429 status code.

Tier	RPM	TPM
Free	10 requests/min	20,000 tokens/min
Standard	60 requests/min	200,000 tokens/min

Errors

The API returns standard HTTP status codes and a JSON error body.

Error Response

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

Code	Description
`401`	Invalid or missing API key
`402`	Insufficient wallet balance
`429`	Rate limit exceeded
`500`	Internal server error

Chat Completions

POST

POST https://ham-iran.ir/v1/chat/completions

Creates a chat completion for the given messages. This endpoint is fully compatible with the OpenAI Chat Completions API.

Request Body

model string Required

ID of the model to use. See the models section for available models.

messages array Required

A list of messages comprising the conversation. Each message has a role and content.

Role	Description
`system`	Sets the behavior and personality of the assistant
`user`	Messages from the user
`assistant`	Previous responses from the assistant

temperature number Optional

Sampling temperature between 0 and 2. Higher values make the output more random. Defaults to 1.

max_tokens integer Optional

Maximum number of tokens to generate in the response. Defaults to model's max output.

stream boolean Optional

If set to true, partial message deltas will be sent as server-sent events (SSE). Defaults to false.

top_p number Optional

Nucleus sampling. The model considers tokens with top_p probability mass. Defaults to 1.

Response

Returns a chat completion object.

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

Streaming

When stream is true, the API returns server-sent events (SSE). Each event contains a partial response delta.

Stream Event

data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":"!"}}]}

data: [DONE]

Available Models

Model ID	Description	Max Tokens
`gpt-4o-mini`	Fast and affordable model for most tasks	128,000

Examples

$ cURL

bash

curl https://ham-iran.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hm-your-api-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'

Py Python (OpenAI SDK)

python

from openai import OpenAI

client = OpenAI(
    api_key="hm-your-api-key",
    base_url="https://ham-iran.ir/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

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

JS Node.js (OpenAI SDK)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "hm-your-api-key",
  baseURL: "https://ham-iran.ir/v1"
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" }
  ]
});

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

PHP PHP (cURL)

php

<?php
$ch = curl_init("https://ham-iran.ir/v1/chat/completions");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer hm-your-api-key"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "model" => "gpt-4o-mini",
        "messages" => [
            ["role" => "system", "content" => "You are a helpful assistant."],
            ["role" => "user", "content" => "Hello!"]
        ]
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data["choices"][0]["message"]["content"];