POST/v1/embeddings

Embeddings

Vector embeddings for one or more strings.

Request

HTTP: POST
URL: /v1/embeddings
Auth: api_key

Try it

# single string
curl https://api.fightclub.pro/v1/embeddings \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"fc:openai/text-embedding-3-small","input":"Hello"}'

# batch
curl https://api.fightclub.pro/v1/embeddings \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"fc:openai/text-embedding-3-large","input":["doc one","doc two"]}'

Example response

{
  "object": "list",
  "model": "openai/text-embedding-3-small",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789, "...1533 more floats"] }
  ],
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

A representative 200 body. Ids and timestamps are illustrative.

Body parameters

Name	Type	Default	Description
model*	string	—	Embedding model reference. Must start with fc:, slot: or match: (e.g. "fc:openai/text-embedding-3-small"). A bare name returns 400 invalid_model_ref.
input*	string \| string[] \| number[] \| number[][]	—	A single string, an array of up to 2,048 strings, an array of token ids, or an array of up to 2,048 token-id arrays. Text items are capped at ~100,000 characters and token-id lists at 100,000 ids. Pre-tokenised input is what the official OpenAI Python SDK sends by default, and it is forwarded to the provider unchanged. It is only accepted for OpenAI embedding models, because token ids from an OpenAI tokenizer mean nothing to bge-m3, mistral-embed or voyage.
user	string	optional	Optional. Attribute the call to one of your customers. The FC-Customer header takes precedence over this field.
FC-Customer	header	optional	Optional. Attribute the cost to an FC Customer for budgets + reporting.

* required.

Headers

Header	Dir	Description
FC-Customer	req →	Attribute the cost to a customer for budgets + reporting.
FC-Cache / FC-Cache-TTL	req →	Opt the call into the response cache.
X-Request-Id	← res	Unique id for this request.
X-Ringside-Model-Resolved	← res	The concrete model that ran.
FC-Cache-Status / -Cache-Key / -Cache-Age	← res	Response-cache hit/miss, key and age.

Response fields

Name	Type	Description
object	string	Always "list".
model	string	The resolved provider/model that ran.
data	array	One { object:"embedding", index, embedding:number[] } per input, in request order.
usage	object	{ prompt_tokens, total_tokens } — embeddings have no completion tokens.

Errors

401missing_tokenNo Authorization header was sent.
401invalid_auth_schemeThe scheme was neither Bearer nor Client.
401invalid_token_formatA Bearer token not prefixed ko_.
401invalid_tokenThe API key is unknown, revoked or expired.
403insufficient_scopeThe key is valid but lacks the required scope.
400invalid_jsonBody is not valid JSON.
400missing_modelmodel is absent.
400missing_inputinput is absent.
400invalid_inputinput is not one of the four accepted shapes, mixes strings and token ids in one array, or contains a token id that is not a non-negative integer.
400input_token_ids_unsupportedPre-tokenised integer input was sent to a model that is not an OpenAI embedding model. Send strings instead.
422input_token_ids_unsupportedThe provider itself rejected pre-tokenised integer input. Send strings instead.
400input_too_largeOver 2,048 items, or an item over the ~100,000-char / 100,000-token cap.
402wallet_emptyAPI pool balance is zero — top up.
503platform_not_configuredNo provider key configured for the model.
503upstream_unavailableProvider returned an error.

See the full error reference.

Notes

·model must be an fc:, slot: or match: ref. A bare name like text-embedding-3-small returns 400 invalid_model_ref.
·dimensions and encoding_format are not implemented. Sending them is accepted and ignored: vectors come back full-width and billed full-width.
·Batch up to 2,048 strings per call to amortize latency.
·The stock OpenAI Python SDK works unchanged: its default path tiktoken-encodes your text and sends integer token ids, which this endpoint accepts and forwards for OpenAI embedding models. You do not need check_embedding_ctx_length=False.

Examples

embeddings-search →