امبدینگ

POST /v1/embeddings متن را به بردارهای عددی تبدیل می‌کند، برای جستجوی معنایی، RAG و خوشه‌بندی. قرارداد آن با OpenAI یکسان است و هزینهٔ واقعی هر درخواست در usage.cost همان پاسخ برمی‌گردد.

POST/v1/embeddingsاحراز هویت Bearer

Create embeddings

Generate vector embeddings from text input. OpenAI-compatible: point your existing OpenAI SDK at Hormouz's base URL and call client.embeddings.create(...) without any code changes.

Supported models: Any supported embedding model, including openai/text-embedding-3-small, openai/text-embedding-3-large, and others. See GET /v1/models?modality=embedding for the full list.

Images — openai/clip: that model embeds pictures as well as text, into the same 768-dimensional space, so a written query can be compared against a photo with plain cosine similarity. Send the picture in image instead of input (an https:// URL or a data:image/...;base64,... URI). Send exactly one of the two: a request carrying both is rejected, because CLIP would otherwise silently drop the text and embed only the image. dimensions does not apply, and usage.prompt_tokens is 0 — CLIP reports no token count. Billed per second of model runtime rather than per token.

Billing: A hold is placed before the upstream call based on an estimated token count. After the response arrives, the actual cost (from usage.cost in the response) is settled inline: the hold is released and the exact charge is deducted in a single transaction. No async settlement or cost-resolver involvement.

Batch input: Pass an array of strings to embed multiple texts in one call. Each string produces one embedding vector in the response's data array.

پارامترها

فیلد	in	نوع	توضیح
`Idempotency-Key`	header	string	Optional deduplication token (any string up to 200 characters). How it works: Same key + same request body → cached response replayed (safe retry) Same key + different body → `409 CONFLICT` error Keys expire after 24 hours When to use: Add this header when you want to safely retry a request after a network timeout without risking a duplicate operation.

بدنه درخواستالزامی

فیلد	نوع	توضیح
`model`الزامی	string	The embedding model to use (e.g., `openai/text-embedding-3-small`). نمونه: `openai/text-embedding-3-small`
`input`	string \| array of string	Text to embed. Required for every model except when embedding a picture with `openai/clip`, where `image` takes its place. Exactly one of `input` or `image` must be present. نمونه: `The food was delicious.`
`image`	string \| array of string	Image(s) to embed — `openai/clip` only, and an extension to the OpenAI API (the official SDKs do not expose it, so send a plain HTTP request). Each value is an `https://`/`http://` URL or a `data:image/...;base64,...` URI. Mutually exclusive with `input`. نمونه: `https://example.com/cat.jpg`
`encoding_format`	string	Output format for the embedding vectors. پیش‌فرض: `float` مقادیر مجاز: `float` · `base64`
`dimensions`	integer	Number of dimensions for the output vectors (model-dependent). Only supported by models that allow dimension reduction (e.g., `text-embedding-3-small` supports 512 or 1536).

نمونه

curlPythonJavaScriptGo

curl https://api.hormouz.net/v1/embeddings \
  -H "Authorization: Bearer ng-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "The food was delicious."
  }'

from openai import OpenAI

client = OpenAI(api_key="ng-YOUR_API_KEY", base_url="https://api.hormouz.net/v1")

resp = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input="The food was delicious.",
)
print(resp.data[0].embedding[:8])

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "ng-YOUR_API_KEY", baseURL: "https://api.hormouz.net/v1" });

const resp = await client.embeddings.create({
  model: "openai/text-embedding-3-small",
  input: "The food was delicious.",
});
console.log(resp.data[0].embedding.slice(0, 8));

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "openai/text-embedding-3-small",
		"input": "The food was delicious.",
	})
	req, _ := http.NewRequest("POST", "https://api.hormouz.net/v1/embeddings", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer ng-YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data []struct {
			Embedding []float64 `json:"embedding"`
		} `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data[0].Embedding[:8])
}

پاسخ‌ها

200

Embeddings created successfully.

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.0067,
        -0.0392,
        0.0341,
        0.0287
      ]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8,
    "cost": 1.6e-7
  }
}

400

The request body or query parameters are invalid. Check the error.code and error.message fields for details. Codes the gateway emits at 400:

BAD_REQUEST: generic malformed JSON / missing required field.
INVALID_TOOLS: the tools array, plugins field, or model's :online suffix uses an unsupported shape. The response names the offender and links to the supported form. See the dedicated InvalidTools response below for the three triggers and migration hints.
UNSUPPORTED_TOOL: a built-in tool (file_search, code_interpreter, computer_use, mcp) whose pricing dimension is not yet wired into the gateway hold estimator.
INVALID_AUDIO_FORMAT: input_audio.format value is not in the supported set. The envelope lists every supported codec name. The gateway accepts both short names (wav, webm) and full MIME aliases (audio/wav, audio/webm); anything else fails fast at admission. See API guide §8b.
AUDIO_NOT_SUPPORTED_ON_RESPONSES: input_audio content part sent to POST /v1/responses. The Responses API has no audio content type today; resend to POST /v1/chat/completions instead.

401

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "status": 401
  }
}

402

Insufficient credit balance.

409

Idempotency key conflict: you sent the same Idempotency-Key with a different request body.

429

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

499

Your HTTP client cancelled the request before the gateway finished. No charge: the hold has been released. The most common cause is a 30 s default client timeout against a model whose p95 latency is 45-60 s; bump your client timeout to 120 s.

Retries with the same Idempotency-Key will replay this 499 forever (the prior outcome is "you cancelled"). For an actual re-attempt, mint a fresh Idempotency-Key. See docs/CUSTOMER_ERROR_HANDLING.md §3 for the full contract.

{
  "error": {
    "code": "CLIENT_CLOSED",
    "message": "Client disconnected before response",
    "status": 499
  }
}

500

Unexpected server error. Please retry with exponential backoff. If the issue persists, contact your admin.

502

The upstream AI provider is temporarily unavailable. Retry with exponential backoff (1s, 2s, 4s) using the same Idempotency-Key: if the upstream actually completed the work and only the response failed, the gateway replays the cached success without a second charge. Holds are released automatically on upstream failures.

503

504

The gateway's 120 s upstream deadline elapsed before the upstream provider produced a response. Retry with the same Idempotency-Key so a delayed-but-eventually-successful upstream call can be replayed instead of re-charged. Consider switching to a faster model or capping max_tokens if this recurs.

{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Upstream did not respond before timeout",
    "status": 504
  }
}