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[]	—	A single string, or an array of up to 2,048 strings. Each item is capped at ~100,000 characters.
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 a string or array of strings.
400input_too_largeOver 2,048 items, or an item over the ~100,000-char 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.

Examples

embeddings-search →