> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Estimate embedding credits

> Estimate credits + per-modality breakdown WITHOUT dispatching. Use this BEFORE a real POST /v1/embeddings to preview cost. Same DTO shape as POST /v1/embeddings minus `encoding_format` and `user` (irrelevant when no charge is made).

Estimates are upper bounds based on pre-fetch input; actual `credits_charged` from POST /v1/embeddings may differ slightly for URL-fetched media (image / video bytes whose server-side tokenization can be more or less aggressive than the local estimator).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/embeddings/estimate
openapi: 3.0.0
info:
  title: Aurous Labs API
  description: >-
    Generate AI images with custom LoRA styles.


    ## Authentication

    All requests require an API key passed in the `X-Api-Key` header.

    Create API keys in your
    [dashboard](https://app.aurous-labs.com/dashboard/api-keys).


    ## Closed-beta access gate

    API keys are scoped to a user. If that user's account is not approved for
    the closed beta, every request returns `403` with one of these `error.code`
    values:


    - `account_pending` — awaiting review

    - `account_rejected` — declined post-signup

    - `account_suspended` — was approved, then suspended


    There is no retry — contact support to be approved. The same codes are
    emitted by the WebSocket gateway via 4001 close.


    ## Common headers

    Every response carries `Aurous-Request-Id` (a server-minted `req_<ULID>` for
    support tracing) and `Aurous-Version` (the API version applied to the
    response). Optionally pin a version on the request with `Aurous-Version:
    YYYY-MM-DD` — defaults to your team's pinned version.


    ## Quick Start

    ```bash

    curl -X POST https://api.aurous-labs.com/v1/images \
      -H "X-Api-Key: al_live_your_key" \
      -H "Content-Type: application/json" \
      -d '{"prompt": "A golden sunset over mountains", "lora_id": "your-lora-id", "size": "2k_1_1"}'
    ```
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.aurous-labs.com
    description: Production
  - url: https://api.preprod.aurous-labs.com
    description: Preprod (staging)
security: []
tags:
  - name: Seedance (raw)
    description: >-
      Drop-in raw passthrough for Seedance video generation. Point the official
      Seedance provider SDK at this API's base URL and authenticate with your
      Aurous API key in the `X-Api-Key` header — request bodies are forwarded to
      the provider verbatim and responses come back shape-identical, so you keep
      the provider's exact request/response shapes. Task ids are Aurous-native
      `vid_…` ids. Billing rides response headers, not the body:
      `Aurous-Credits-Held` on the create response and `Aurous-Credits-Charged`
      on a settled, succeeded task read — the body itself stays provider-shaped.
paths:
  /v1/embeddings/estimate:
    post:
      tags:
        - Embeddings
      summary: Estimate embedding credits
      description: >-
        Estimate credits + per-modality breakdown WITHOUT dispatching. Use this
        BEFORE a real POST /v1/embeddings to preview cost. Same DTO shape as
        POST /v1/embeddings minus `encoding_format` and `user` (irrelevant when
        no charge is made).


        Estimates are upper bounds based on pre-fetch input; actual
        `credits_charged` from POST /v1/embeddings may differ slightly for
        URL-fetched media (image / video bytes whose server-side tokenization
        can be more or less aggressive than the local estimator).
      operationId: V1EmbeddingsController_estimate
      parameters:
        - name: Aurous-Version
          in: header
          required: false
          description: >-
            Optional API version pin (YYYY-MM-DD). Defaults to your team's
            pinned version, or the system default `2026-07-16` for
            unauthenticated requests.
          schema:
            type: string
            example: '2026-07-16'
            pattern: ^\d{4}-\d{2}-\d{2}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingEstimateRequestDto'
      responses:
        '200':
          description: Estimate produced.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingEstimateResponse'
          headers:
            Aurous-Request-Id:
              description: Server-minted request id. Quote this in support tickets.
              schema:
                type: string
                example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
            Aurous-Version:
              description: API version pin applied to this response (YYYY-MM-DD).
              schema:
                type: string
                example: '2026-07-16'
            X-RateLimit-Limit:
              description: Bucket capacity (max tokens) for this endpoint class.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Tokens remaining after this request.
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: >-
                Epoch seconds when the bucket would be full again, assuming no
                further requests.
              schema:
                type: integer
                example: 1700000060
        '400':
          description: >-
            Validation error. Possible codes: `model_wrong_kind`,
            `embeddings_unsupported_dimensions`,
            `embeddings_batch_not_supported`, `embeddings_input_too_many_items`,
            `embeddings_video_unsupported`, `embeddings_input_too_large`.
            Standard `invalid_request` is also returned for DTO violations
            (missing fields, type mismatches).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Aurous-Request-Id:
              description: Server-minted request id. Quote this in support tickets.
              schema:
                type: string
                example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
            Aurous-Version:
              description: API version pin applied to this response (YYYY-MM-DD).
              schema:
                type: string
                example: '2026-07-16'
            X-RateLimit-Limit:
              description: Bucket capacity (max tokens) for this endpoint class.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Tokens remaining after this request.
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: >-
                Epoch seconds when the bucket would be full again, assuming no
                further requests.
              schema:
                type: integer
                example: 1700000060
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Aurous-Request-Id:
              description: Server-minted request id. Quote this in support tickets.
              schema:
                type: string
                example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
            Aurous-Version:
              description: API version pin applied to this response (YYYY-MM-DD).
              schema:
                type: string
                example: '2026-07-16'
            X-RateLimit-Limit:
              description: Bucket capacity (max tokens) for this endpoint class.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Tokens remaining after this request.
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: >-
                Epoch seconds when the bucket would be full again, assuming no
                further requests.
              schema:
                type: integer
                example: 1700000060
        '403':
          description: >-
            Access denied. code: `model_disabled` (the requested model is
            currently inactive).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Aurous-Request-Id:
              description: Server-minted request id. Quote this in support tickets.
              schema:
                type: string
                example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
            Aurous-Version:
              description: API version pin applied to this response (YYYY-MM-DD).
              schema:
                type: string
                example: '2026-07-16'
            X-RateLimit-Limit:
              description: Bucket capacity (max tokens) for this endpoint class.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Tokens remaining after this request.
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: >-
                Epoch seconds when the bucket would be full again, assuming no
                further requests.
              schema:
                type: integer
                example: 1700000060
        '404':
          description: 'Resource not found. code: `model_not_found` (unknown model slug).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Aurous-Request-Id:
              description: Server-minted request id. Quote this in support tickets.
              schema:
                type: string
                example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
            Aurous-Version:
              description: API version pin applied to this response (YYYY-MM-DD).
              schema:
                type: string
                example: '2026-07-16'
            X-RateLimit-Limit:
              description: Bucket capacity (max tokens) for this endpoint class.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Tokens remaining after this request.
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: >-
                Epoch seconds when the bucket would be full again, assuming no
                further requests.
              schema:
                type: integer
                example: 1700000060
        '429':
          description: >-
            Rate limit exceeded on the `estimate_post` bucket (120/min
            sustained). See `Retry-After` header.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Present on 429 (rate limit) and
                on 503 provider_unavailable. Prefer this over computing
                X-RateLimit-Reset − now.
              schema:
                type: integer
                example: 12
            X-RateLimit-Limit:
              description: Bucket capacity (max tokens) for this endpoint class.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Tokens remaining after this request.
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: >-
                Epoch seconds when the bucket would be full again, assuming no
                further requests.
              schema:
                type: integer
                example: 1700000060
            Aurous-Request-Id:
              description: Server-minted request id. Quote this in support tickets.
              schema:
                type: string
                example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP
            Aurous-Version:
              description: API version pin applied to this response (YYYY-MM-DD).
              schema:
                type: string
                example: '2026-07-16'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - api-key: []
components:
  schemas:
    EmbeddingEstimateRequestDto:
      type: object
      properties:
        model:
          type: string
          description: >-
            Public model slug (e.g. "aurous-embed-vision-1.0"). Pass exactly as
            listed by GET /v1/models.
          example: aurous-embed-vision-1.0
        input:
          description: >-
            Input — accepts a string OR an array of content parts ({type:
            "text"|"image_url"|"video_url"}) for multimodal. String-array
            (string[]) batch input is NOT accepted on v1 (same rules as POST
            /v1/embeddings).
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/EmbedContentPartDto'
        dimensions:
          type: integer
          description: >-
            Output vector dimensions. Most models return a fixed dimension and
            reject this parameter. If the model does not support `dimensions`,
            the estimate returns 400 `embeddings_unsupported_dimensions` —
            identical to the dispatch path, so an estimate and a real request
            fail at the same gate.
          example: 1024
      required:
        - model
        - input
    EmbeddingEstimateResponse:
      type: object
      properties:
        estimated:
          type: boolean
          description: >-
            Always true — distinguishes this from a real /v1/embeddings response
            (which uses object: 'list').
          example: true
        tokens:
          description: Estimated token counts per modality + total.
          allOf:
            - $ref: '#/components/schemas/EmbeddingEstimateTokens'
        credits_estimated:
          type: number
          description: >-
            Estimated credits for this request. Real `credits_charged` from POST
            /v1/embeddings may differ slightly for URL-fetched media (image /
            video tokenization variance), but the estimate is generally a tight
            upper bound.
          example: 0.19125
        breakdown:
          description: Per-modality credit decomposition + model echo.
          allOf:
            - $ref: '#/components/schemas/EmbeddingEstimateBreakdown'
      required:
        - estimated
        - tokens
        - credits_estimated
        - breakdown
    ErrorResponse:
      type: object
      properties:
        error:
          description: Error payload
          allOf:
            - $ref: '#/components/schemas/ErrorPayload'
      required:
        - error
    EmbedContentPartDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - video_url
          description: Content part type.
        text:
          type: string
          description: Text payload (required when type is "text").
        image_url:
          type: object
          description: >-
            Image reference (required when type is "image_url"). { url: string
            }.
        video_url:
          type: object
          description: >-
            Video reference (required when type is "video_url"). { url: string
            }.
      required:
        - type
    EmbeddingEstimateTokens:
      type: object
      properties:
        text:
          type: number
          description: >-
            Estimated text tokens (tiktoken-equivalent count for any text
            content parts).
          example: 5000
        image:
          type: number
          description: >-
            Estimated visual (image) tokens. Conservative high-tier per-image
            cost; 0 when no image_url parts.
          example: 2000
        video:
          type: number
          description: Estimated video tokens. 0 when no video_url parts.
          example: 0
        total:
          type: number
          description: >-
            Sum of text + image + video tokens — what the model would be charged
            against its context_window.
          example: 7000
      required:
        - text
        - image
        - video
        - total
    EmbeddingEstimateBreakdown:
      type: object
      properties:
        input:
          description: Per-modality credit decomposition.
          allOf:
            - $ref: '#/components/schemas/EmbeddingEstimateBreakdownInput'
        model:
          type: string
          description: Model slug used for the estimate (echoed from the request).
          example: aurous-embed-vision-1.0
      required:
        - input
        - model
    ErrorPayload:
      type: object
      properties:
        type:
          type: string
          description: Broad error category
          example: invalid_request
          enum:
            - invalid_request
            - authentication
            - not_found
            - rate_limit
            - server_error
        code:
          type: string
          description: >-
            Stable error code (programmatic discriminator). Closed-beta gate
            emits one of `account_pending`, `account_rejected`,
            `account_suspended` on 403.
          example: balance_too_low
          enum:
            - invalid_request
            - missing_field
            - invalid_format
            - value_out_of_range
            - unsupported_lora_for_mode
            - generation_not_cancellable
            - prompt_blocked
            - reference_blocked
            - output_moderation_rejected
            - unknown_version
            - mutually_exclusive_input
            - character_not_ready
            - parameter_invalid_combination
            - too_many_reference_images
            - action_not_available
            - upload_invalid
            - balance_too_low
            - idempotency_key_in_use
            - api_key_not_found
            - payload_too_large
            - missing_api_key
            - invalid_api_key
            - revoked_api_key
            - resource_not_found
            - forbidden_resource
            - account_pending
            - account_rejected
            - account_suspended
            - already_approved
            - already_rejected
            - already_suspended
            - invalid_reinstate_target
            - invalid_suspend_target
            - cannot_moderate_admin
            - too_many_requests
            - concurrency_limit_exceeded
            - tpm_rate_limit_exceeded
            - internal_error
            - provider_unavailable
            - provider_timeout
            - provider_not_configured
            - invalid_time_range
            - invalid_bucket_width
            - too_many_buckets
            - too_many_group_by
            - invalid_filter
            - invalid_page_token
            - export_too_large
            - user_already_exists
            - self_invite_forbidden
            - invite_link_failed
            - invite_rate_limited
            - model_not_found
            - model_disabled
            - model_wrong_kind
            - max_tokens_exceeds_hard_cap
            - chat_model_misconfigured
            - embeddings_input_too_large
            - embeddings_unsupported_dimensions
            - pricing_frozen
            - provider_rate_limited
            - chat_provider_request_invalid
            - chat_provider_auth_failed
            - chat_provider_unavailable
            - max_input_tokens_exceeded
            - chat_provider_unknown_error
            - embeddings_provider_unknown_error
            - embeddings_batch_not_supported
            - embeddings_input_too_many_items
            - embeddings_video_unsupported
            - encoding_format_unsupported
            - missing_max_tokens_no_model_default
            - chat_cancel_target_not_found
            - chat_completion_not_found
            - chat_cancel_target_already_terminal
            - chat_cancel_target_not_cancellable
            - tool_choice_required_unsupported
            - response_format_too_large
            - response_format_too_deep
            - invalid_cursor
            - invalid_cursor_for_endpoint
            - model_slug_exists
            - output_expired
            - output_not_available
            - content_filtered
            - image_generation_failed
            - reference_media_invalid
            - reference_media_cap_reached
            - reference_fetch_failed
            - unsupported_auth_method
            - insufficient_scope
            - uploads_expired
            - provider_unknown_error
        message:
          type: string
          description: Human-readable message
          example: Team available balance is 1.5 credits, generation requires 2.0.
        param:
          type: object
          description: Field name when the error is parameter-scoped
          example: prompt
          nullable: true
        doc_url:
          type: string
          description: Documentation link for this error code
          example: https://docs.aurous-labs.com/errors#balance_too_low
        request_id:
          type: string
          description: Echoes Aurous-Request-Id — quote in support tickets
          example: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
      required:
        - type
        - code
        - message
        - doc_url
        - request_id
    EmbeddingEstimateBreakdownInput:
      type: object
      properties:
        text:
          type: number
          description: >-
            Estimated credits for text input. 0 when no text content was present
            in the request.
          example: 0.09375
        visual:
          type: number
          description: >-
            Estimated credits for visual (image) input. 0 when no image_url
            content was present in the request.
          example: 0.0975
        video:
          type: number
          description: >-
            Estimated credits for video input. 0 when no video_url content was
            present in the request.
          example: 0
      required:
        - text
        - visual
        - video
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Your team API key (starts with `al_live_`).

````