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 API platform dashboard after signing in with your mobile number.

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. Every error includes a stable code string for programmatic handling.

Error Response

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

HTTP	code	type	Message
`401`	`missing_api_key`	invalid_request_error	You must provide an API key in the Authorization header.
`401`	`invalid_api_key`	invalid_request_error	Invalid API key provided.
`402`	`insufficient_balance`	insufficient_quota	Insufficient wallet balance. Please top up your account.
`429`	`rate_limit_exceeded`	rate_limit_error	Rate limit exceeded. Please retry after a minute.
`400`	`invalid_json`	invalid_request_error	Invalid JSON in request body.
`405`	`method_not_allowed`	invalid_request_error	Method not allowed for this endpoint.
`400`	`model_required`	invalid_request_error	The "model" field is required.
`400`	`messages_required`	invalid_request_error	The "messages" field is required and must be a non-empty array.
`404`	`model_not_found`	invalid_request_error	The requested model is not available.
`400`	`invalid_messages`	invalid_request_error	Each message must have a valid "role" and "content".
`404`	`not_found`	invalid_request_error	The requested endpoint does not exist.
`502`	`upstream_error`	server_error	Upstream AI service is temporarily unavailable.
`500`	`internal_error`	server_error	An internal server error occurred.

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": "gemini-3.1-flash-lite-preview",
  "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
`gemini-3.1-flash-lite-preview`	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": "gemini-3.1-flash-lite-preview",
    "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="gemini-3.1-flash-lite-preview",
    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: "gemini-3.1-flash-lite-preview",
  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" => "gemini-3.1-flash-lite-preview",
        "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"];