{
  "openapi": "3.1.0",
  "info": {
    "title": "Hibana AI API",
    "version": "2026-11-16",
    "summary": "OpenAI-compatible API for GPT, Claude, Gemini, DeepSeek and other models, billed in Iranian rial.",
    "description": "Hibana (هیبانا) is an OpenAI-compatible gateway: any OpenAI SDK or tool works by setting the base URL to https://api-ai.hibanacloud.ir/v1 and using a Hibana API key. Every successful response carries usage.cost_rial, the cost of that request in rial (1 toman = 10 rial). Model ids and prices: https://hibanacloud.ir/models.json. Docs (Persian): https://hibanacloud.ir/docs. This file describes the request and response fields Hibana handles; unknown request fields are accepted and passed through or ignored, as with OpenAI.",
    "contact": { "name": "Hibana support", "email": "support@hibanacloud.ir", "url": "https://hibanacloud.ir/contact" },
    "termsOfService": "https://hibanacloud.ir/terms"
  },
  "externalDocs": { "description": "Hibana documentation (Persian)", "url": "https://hibanacloud.ir/docs" },
  "servers": [{ "url": "https://api-ai.hibanacloud.ir/v1", "description": "Production" }],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Chat", "description": "Text generation, tools, images/PDF/audio/video input" },
    { "name": "Embeddings" },
    { "name": "Images" },
    { "name": "Audio" },
    { "name": "Decisions", "description": "Typed yes/no, choice and score questions answered with probabilities; billed per input token, output free" },
    { "name": "Account" }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "tags": ["Chat"],
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion (OpenAI Chat Completions format; set stream=true for Server-Sent Events).",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }
        },
        "responses": {
          "200": {
            "description": "The completion. With stream=true: text/event-stream of chat.completion.chunk objects ending with `data: [DONE]` (the usage chunk is sent only with stream_options.include_usage=true; `: keep-alive` comment lines may appear while the model thinks).",
            "headers": { "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitHeaders" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/responses": {
      "post": {
        "tags": ["Chat"],
        "operationId": "createResponse",
        "summary": "Create a model response (OpenAI Responses API format).",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "input"],
                "properties": {
                  "model": { "type": "string", "examples": ["gpt-5-nano"] },
                  "input": { "description": "A string or an array of input items, as in the OpenAI Responses API.", "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }] },
                  "instructions": { "type": "string" },
                  "stream": { "type": "boolean" },
                  "reasoning": { "type": "object", "properties": { "effort": { "type": "string", "examples": ["low"] } } },
                  "max_output_tokens": { "type": "integer" },
                  "tools": { "type": "array", "items": { "type": "object" } }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": { "description": "The response object (or an SSE stream with stream=true).", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/embeddings": {
      "post": {
        "tags": ["Embeddings"],
        "operationId": "createEmbedding",
        "summary": "Create embeddings (for example bge-m3, which runs on Hibana's servers in Iran).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "input"],
                "properties": {
                  "model": { "type": "string", "examples": ["bge-m3"] },
                  "input": {
                    "description": "A string, an array of strings (at most 2048), or token-id arrays. Image-capable models also take items {\"content\":[{type:text|image_url}]}.",
                    "oneOf": [
                      { "type": "string" },
                      { "type": "array", "items": { "type": "string" }, "maxItems": 2048 },
                      { "type": "array", "items": { "type": "integer" } },
                      { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } },
                      { "type": "array", "items": { "type": "object" } }
                    ]
                  },
                  "dimensions": { "type": "integer", "minimum": 1 },
                  "encoding_format": { "type": "string", "enum": ["float", "base64"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The embeddings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "const": "list" },
                    "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "const": "embedding" }, "index": { "type": "integer" }, "embedding": { "oneOf": [{ "type": "array", "items": { "type": "number" } }, { "type": "string" }] } } } },
                    "model": { "type": "string" },
                    "usage": { "$ref": "#/components/schemas/Usage" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/images/generations": {
      "post": {
        "tags": ["Images"],
        "operationId": "createImage",
        "summary": "Generate one image from a prompt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "prompt"],
                "properties": {
                  "model": { "type": "string" },
                  "prompt": { "type": "string" },
                  "size": { "type": "string", "description": "An aspect ratio such as \"16:9\" or \"1:1\".", "examples": ["16:9"] },
                  "quality": { "type": "string" },
                  "style": { "type": "string" },
                  "response_format": { "type": "string", "enum": ["url", "b64_json"], "default": "url", "description": "url: a temporary link on Hibana's storage (download it soon); b64_json: the bytes inline, nothing stored." }
                },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One generated image.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": { "type": "integer" },
                    "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "b64_json": { "type": "string" }, "revised_prompt": { "type": "string" } } } },
                    "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost_rial": { "type": "number" } } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/audio/transcriptions": {
      "post": {
        "tags": ["Audio"],
        "operationId": "createTranscription",
        "summary": "Speech to text (Whisper-compatible multipart request). OpenAI model names such as whisper-1 are accepted and mapped to an audio-capable model.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary", "description": "The audio file (at most 25 MB)." },
                  "model": { "type": "string", "examples": ["whisper-1"] },
                  "language": { "type": "string", "description": "ISO-639-1 hint, for example fa." },
                  "prompt": { "type": "string", "description": "Spelling context (names, terms)." },
                  "response_format": { "type": "string", "enum": ["json", "text"], "default": "json" },
                  "temperature": { "type": "number", "minimum": 0, "maximum": 1 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The transcript.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "text": { "type": "string" },
                    "usage": { "type": "object", "properties": { "type": { "const": "tokens" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost_rial": { "type": "number" } } }
                  }
                }
              },
              "text/plain": { "schema": { "type": "string" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/audio/speech": {
      "post": {
        "tags": ["Audio"],
        "operationId": "createSpeech",
        "summary": "Text to speech (OpenAI-compatible). Returns the finished audio file as raw bytes, not JSON. Billed once after the audio is ready: per 1000 characters of input (Gemini TTS: by text and audio tokens); a failed request is not charged. Unlike the other endpoints, unknown request fields are rejected with 400 unknown_parameter. Guide: https://hibanacloud.ir/docs/text-to-speech",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "input"],
                "additionalProperties": false,
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "A speech model code. The OpenAI names tts-1, tts-1-hd and gpt-4o-mini-tts are accepted and mapped to a default speech model.",
                    "examples": ["elevenlabs/eleven-v4-turbo", "google/gemini-3.8-flash-tts", "minimax/speech-2.8-turbo"]
                  },
                  "input": {
                    "description": "The text to speak (at most 5000 characters, Gemini TTS 3000). On multi-speaker models an array of turns {text, voice?, instructions?}.",
                    "oneOf": [
                      { "type": "string" },
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": ["text"],
                          "properties": { "text": { "type": "string" }, "voice": { "type": "string" }, "instructions": { "type": "string" } }
                        }
                      }
                    ]
                  },
                  "voice": {
                    "description": "A voice of the model (for example sarah, Kore, English_CalmWoman) as a string or {\"id\": \"...\"}. An OpenAI voice name such as alloy becomes the default voice of the model. Omitted: the default voice.",
                    "oneOf": [
                      { "type": "string" },
                      { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } }
                    ]
                  },
                  "instructions": { "type": "string", "description": "Tone and style (Gemini TTS). Not billed." },
                  "response_format": {
                    "type": "string",
                    "enum": ["mp3", "wav", "pcm"],
                    "description": "ElevenLabs: mp3 (default), wav, pcm. Gemini TTS: wav (default), pcm. MiniMax: mp3. pcm is 24 kHz mono signed 16-bit little-endian. opus, aac and flac are rejected."
                  },
                  "speed": { "type": "number", "description": "Speaking speed on models that support it (Gemini TTS, MiniMax); dropped elsewhere." },
                  "stream_format": { "type": "string", "enum": ["audio"], "description": "Only \"audio\" (the whole file is sent when ready); \"sse\" is not supported." },
                  "user": { "type": "string", "description": "Ignored." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The audio file.",
            "headers": {
              "X-Hibana-Cost-Rial": { "description": "Rial charged for this request.", "schema": { "type": "integer" } },
              "X-Hibana-Characters": { "description": "Billable characters of the input.", "schema": { "type": "integer" } },
              "X-Request-Id": { "schema": { "type": "string" } }
            },
            "content": {
              "audio/mpeg": { "schema": { "type": "string", "format": "binary" } },
              "audio/wav": { "schema": { "type": "string", "format": "binary" } },
              "audio/pcm;rate=24000;channels=1": { "schema": { "type": "string", "format": "binary" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/decisions": {
      "post": {
        "tags": ["Decisions"],
        "operationId": "createDecision",
        "summary": "Decision models (OpenAI's Decisions API): answer typed questions about an input with probabilities, never text. Question types: predicate (yes/no), choice (2 to 255 options), score (2 to 10 ordered levels). Billed per INPUT token only (text, images, audio and video all count); the output is free. The wallet is checked against an upper bound before the call, the charge is the reported token count. Unlike the other endpoints, unknown request fields are rejected with 400 unknown_parameter. Works with the official OpenAI SDKs (client.decisions.create). Guide: https://hibanacloud.ir/docs/decisions",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "input", "questions"],
                "additionalProperties": false,
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "A decision model code. The OpenAI name gpt-6-luna is accepted and maps to openai/gpt-6-luna-decisions.",
                    "examples": ["typesafe/jev-1.14", "cloudflare/clef-flash", "openai/gpt-6-luna-decisions", "perplexity/pplx-decider-v1.2", "google/gemini-decision-1"]
                  },
                  "input": {
                    "description": "What the questions are about: a string, or an array of OpenAI items (messages with role user, developer, system or assistant and parts input_text, input_image {image_url, detail?}, input_json {data}; function_call and function_call_output items; reasoning items are ignored). Hibana extensions: input_audio {input_audio: {data (base64), format}} and input_video {video_url: data URL} on models that accept them (Gemini Decision 1).",
                    "oneOf": [
                      { "type": "string" },
                      { "type": "array", "items": { "type": "object" } }
                    ]
                  },
                  "questions": {
                    "type": "array",
                    "description": "The questions, answered in the same order. At most 64 to 400 per request depending on the model.",
                    "minItems": 1,
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "required": ["type", "instructions"],
                          "additionalProperties": false,
                          "properties": {
                            "type": { "const": "predicate" },
                            "name": { "type": "string" },
                            "instructions": { "type": "string", "description": "A statement about the input; the answer is the probability that it is true." }
                          }
                        },
                        {
                          "type": "object",
                          "required": ["type", "instructions", "choices"],
                          "additionalProperties": false,
                          "properties": {
                            "type": { "const": "choice" },
                            "name": { "type": "string" },
                            "instructions": { "type": "string" },
                            "choices": {
                              "type": "array",
                              "minItems": 2,
                              "maxItems": 255,
                              "items": {
                                "type": "object",
                                "required": ["value"],
                                "additionalProperties": false,
                                "properties": {
                                  "value": { "type": ["string", "boolean"], "description": "Typed: the string \"true\" and the boolean true are different choices." },
                                  "description": { "type": "string" }
                                }
                              }
                            }
                          }
                        },
                        {
                          "type": "object",
                          "required": ["type", "instructions", "levels"],
                          "additionalProperties": false,
                          "properties": {
                            "type": { "const": "score" },
                            "name": { "type": "string" },
                            "instructions": { "type": "string" },
                            "levels": {
                              "type": "array",
                              "minItems": 2,
                              "maxItems": 10,
                              "description": "Ordered levels, lowest first.",
                              "items": {
                                "type": "object",
                                "required": ["label"],
                                "additionalProperties": false,
                                "properties": { "label": { "type": "string" }, "description": { "type": "string" } }
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One answer per question, in order. A refusal answer is charged like any other.",
            "headers": {
              "X-Hibana-Cost-Rial": { "description": "Rial charged for this request.", "schema": { "type": "integer" } },
              "X-Request-Id": { "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "object": { "const": "decision" },
                    "model": { "type": "string" },
                    "answers": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": { "type": { "const": "predicate" }, "name": { "type": ["string", "null"] }, "probability": { "type": "number", "minimum": 0, "maximum": 1 } }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": { "const": "choice" },
                              "name": { "type": ["string", "null"] },
                              "choice": { "type": ["string", "boolean"], "description": "The most likely choice, with its original type." },
                              "confidence": { "type": "number" },
                              "probabilities": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": ["string", "boolean"] }, "probability": { "type": "number" } } } }
                            }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": { "const": "score" },
                              "name": { "type": ["string", "null"] },
                              "score": { "type": "number", "description": "The probability-weighted level position; can be fractional." },
                              "confidence": { "type": "number" },
                              "probabilities": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "integer" }, "label": { "type": "string" }, "probability": { "type": "number" } } } }
                            }
                          },
                          {
                            "type": "object",
                            "properties": { "type": { "const": "refusal" }, "name": { "type": ["string", "null"] } }
                          }
                        ]
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "input_tokens": { "type": "integer" },
                        "input_tokens_details": { "type": "object", "properties": { "cached_tokens": { "type": "integer" } } },
                        "output_tokens": { "type": "integer" },
                        "total_tokens": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/systemone": {
      "post": {
        "tags": ["Decisions"],
        "operationId": "createSystemOne",
        "summary": "Decision models in TypeSafe's System One format (also OpenRouter's): named questions of type noul (yes/no), choice, score or box (find something in an image, Jev only), answered with probabilities. Same models, billing and errors as /decisions. Works with the TypeSafe SDKs (typesafe-sdk, @typesafe-ai/sdk) with base URL https://api-ai.hibanacloud.ir (the host root: the SDK adds /v1/systemone). Guide: https://hibanacloud.ir/docs/decisions",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "state", "questions"],
                "additionalProperties": false,
                "properties": {
                  "model": { "type": "string", "description": "A decision model; bare ids such as jev-1.14 and jev-latest also work.", "examples": ["jev-1.14", "typesafe/jev-1.14"] },
                  "state": { "description": "What the questions are about: a string, an object, or an array of strings, objects and image_url parts.", "oneOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }] },
                  "questions": {
                    "type": "object",
                    "description": "Questions keyed by the name their answer comes back under.",
                    "additionalProperties": {
                      "type": "object",
                      "required": ["type"],
                      "properties": {
                        "type": { "enum": ["noul", "choice", "score", "box"] },
                        "instructions": { "type": "string" },
                        "criteria": { "description": "noul: {true?, false?} descriptions; choice: {option: description}; score: ordered list of level descriptions; box: none." }
                      }
                    }
                  },
                  "assets": {
                    "type": "object",
                    "description": "Images referenced from the text, keyed by their reference.",
                    "additionalProperties": {
                      "type": "object",
                      "required": ["format", "data_base64"],
                      "properties": { "format": { "enum": ["png", "jpg", "jpeg"] }, "data_base64": { "type": "string" } }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answers keyed by question name.",
            "headers": { "X-Hibana-Cost-Rial": { "description": "Rial charged for this request.", "schema": { "type": "integer" } } },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "model": { "type": "string" },
                    "answers": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "description": "noul: {type, noul}; choice: {type, choice, probabilities, confidence}; score: {type, score, probabilities, legend, confidence}; box: {type, box {top, bottom, left, right}, confidence}."
                      }
                    },
                    "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/decisions/models": {
      "get": {
        "tags": ["Decisions"],
        "operationId": "listDecisionModels",
        "summary": "The decision models with their question types, input limits and rial prices (input per million tokens; the output is free).",
        "responses": {
          "200": {
            "description": "The decision models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "const": "list" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "owned_by": { "type": "string" },
                          "question_types": { "type": "array", "items": { "type": "string" } },
                          "inputs": { "type": "array", "items": { "type": "string" } },
                          "max_questions": { "type": "integer" },
                          "max_choices": { "type": "integer" },
                          "max_score_levels": { "type": "integer" },
                          "max_input_characters": { "type": "integer" },
                          "max_images": { "type": "integer" },
                          "image_formats": { "type": "array", "items": { "type": "string" } },
                          "max_audio_clips": { "type": "integer" },
                          "max_videos": { "type": "integer" },
                          "context_length": { "type": "integer" },
                          "pricing": {
                            "type": "object",
                            "properties": {
                              "currency": { "const": "IRR" },
                              "unit": { "const": "token" },
                              "input_per_million_tokens": { "type": "number" },
                              "input_per_million_tokens_usd": { "type": "number" },
                              "output_per_million_tokens": { "type": "number", "description": "Always 0: the output is free." }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/models": {
      "get": {
        "tags": ["Account"],
        "operationId": "listModels",
        "summary": "List the model ids available to this key (OpenAI format). Prices and capabilities without a key: https://hibanacloud.ir/models.json",
        "responses": {
          "200": {
            "description": "The models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "const": "list" },
                    "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "examples": ["anthropic/claude-sonnet-5.5"] }, "object": { "const": "model" }, "owned_by": { "type": "string" }, "created": { "type": "integer" } } } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/user/balance": {
      "get": {
        "tags": ["Account"],
        "operationId": "getBalance",
        "summary": "The wallet balance of the key's account.",
        "responses": {
          "200": {
            "description": "The balance in rial.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "object": { "const": "user.balance" }, "balance": { "type": "number" }, "currency": { "const": "IRR" } }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Hibana API key: Authorization: Bearer <key>. Create one at https://hibanacloud.ir/docs/get-api-key" }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Retry-safe key: a repeated request with the same key returns the first result (header Idempotent-Replayed: true) instead of calling the model again.",
        "schema": { "type": "string", "maxLength": 255 }
      }
    },
    "headers": {
      "RateLimitHeaders": {
        "description": "Requests left in the current window. Related headers: X-RateLimit-Limit, X-RateLimit-Tier (account level); a 429 carries Retry-After.",
        "schema": { "type": "integer" }
      }
    },
    "responses": {
      "Error": {
        "description": "OpenAI-shaped error. Common codes: 400 model_not_found, 401 invalid_api_key, 402 insufficient_funds or budget_exceeded, 403 model_not_allowed, 429 rate_limited.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string", "enum": ["invalid_request_error", "authentication_error", "permission_error", "not_found_error", "rate_limit_error", "server_error", "billing_error"] },
              "code": { "type": ["string", "null"] },
              "param": { "type": ["string", "null"] }
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": { "type": "integer" },
          "completion_tokens": { "type": "integer" },
          "total_tokens": { "type": "integer" },
          "cost_rial": { "type": "number", "description": "The cost of this request in Iranian rial, as deducted from the wallet." }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role"],
        "properties": {
          "role": { "type": "string", "enum": ["system", "developer", "user", "assistant", "tool"] },
          "content": { "description": "Text, or an array of parts: text, image_url, file (PDF/text files), input_audio, video_url.", "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "object" } }, { "type": "null" }] },
          "name": { "type": "string" },
          "tool_calls": { "type": "array", "items": { "type": "object" } },
          "tool_call_id": { "type": "string" }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string", "description": "A model id from GET /models or https://hibanacloud.ir/models.json", "examples": ["gpt-5-nano", "anthropic/claude-sonnet-5.5"] },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } },
          "stream": { "type": "boolean" },
          "stream_options": { "type": "object", "properties": { "include_usage": { "type": "boolean" } } },
          "max_tokens": { "type": "integer" },
          "max_completion_tokens": { "type": "integer", "description": "Wins over max_tokens. On reasoning models it includes reasoning tokens." },
          "temperature": { "type": "number", "description": "Clamped to the model's range; omitted for models that reject it." },
          "top_p": { "type": "number" },
          "stop": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
          "n": { "type": "integer", "const": 1 },
          "tools": { "type": "array", "maxItems": 50, "items": { "type": "object" } },
          "tool_choice": { "oneOf": [{ "type": "string", "enum": ["auto", "none", "required"] }, { "type": "object" }] },
          "parallel_tool_calls": { "type": "boolean" },
          "response_format": { "type": "object", "description": "json_object or json_schema, where the model supports it." },
          "reasoning_effort": { "type": "string", "examples": ["low", "medium", "high"] },
          "verbosity": { "type": "string" },
          "seed": { "type": "integer" },
          "frequency_penalty": { "type": "number" },
          "presence_penalty": { "type": "number" },
          "user": { "type": "string" }
        },
        "additionalProperties": true
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "const": "chat.completion" },
          "created": { "type": "integer" },
          "model": { "type": "string", "description": "Echoes the model string that was sent." },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": ["string", "null"] }, "tool_calls": { "type": "array", "items": { "type": "object" } } } },
                "finish_reason": { "type": "string", "enum": ["stop", "length", "tool_calls", "content_filter"] }
              }
            }
          },
          "usage": { "$ref": "#/components/schemas/Usage" }
        }
      }
    }
  }
}
