POST/v1/embeddings

Create embeddings

OpenAI-compatible embeddings for text or token-ID input, singly or in a batch. Always one JSON body; stream: true is refused.

No response cache and no Idempotency-Key replay: a repeated request is a new billable call. Billing is on input tokens only. The response carries no usage.cost.

Authentication: Bearer API key in the Authorization header

Request body

  • modelstringrequired

    An embedding model slug. A chat model is refused with unsupported_capability.

  • inputstring | array<string> | array<integer> | array<array<integer>>required

    A nonempty string, a list of nonempty strings, an array of token IDs (one vector), or a list of token-ID arrays (a batch). Do not mix text and tokens. Token IDs must match the model's tokenizer.

  • dimensionsinteger

    Output size, where the model supports reducing it (text-embedding-3 models do, ada-002 does not).

  • encoding_formatenum

    float arrays or base64 strings. The OpenAI Python SDK asks for base64 and decodes it for you.

    "float""base64"
    Default: "float"
  • streamboolean

    Omit or send false. true is refused.

  • userstring

    End-user id for your own attribution, up to 1,024 characters. Not forwarded to the provider.

Responses

  • 200

    One vector per input, in input order.

    Response
    • objectstring
    • modelstring
    • dataarray<object>
      data
      • objectstring
      • indexinteger

        Position of the matching input.

      • embeddingarray<number> | string

        Floats, or a base64 string with encoding_format=base64.

    • usageobject
      usage
      • prompt_tokensinteger
      • total_tokensinteger

        Equals prompt_tokens.

  • 400

    Invalid request. param names the field; code says why (invalid_parameter, unsupported_parameter, unsupported_capability, refusal, previous_response_not_found). Not charged.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 401

    The key is missing, malformed, expired or revoked.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 402

    The organization must act first: card_required, email_unverified, org_under_review, free_tier_requires_payment or promotion_ended. The message names the step; retrying does not help.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 403

    model_not_granted (use an id from GET /v1/models), model_location_not_supported, or a zero-data-retention demand no route can meet.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 429

    insufficient_quota (out of credits, over a spend limit, or the model needs a purchase) and promo_credits_now (a free promotion is used up): add credits, the message names the step. rate_limit_exceeded, free_limit_reached, admission_capacity_exceeded: wait Retry-After seconds and retry.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 503

    gateway_unavailable, gateway_draining, unavailable_route or deadline_exceeded. Retry with backoff, honoring Retry-After when present.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"

Request

curl https://api.experientiallabs.ai/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": ["first document", "second document"]}'

Response

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456,
        0.0789
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.0321,
        -0.0654,
        0.0987
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4
  }
}

https://api.experientiallabs.ai/v1/embeddings