> ## 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. # Create embeddings > Create embeddings from text and/or visual content (images, video). Multimodal input is combined into a SINGLE embedding (the underlying model concatenates parts into one document representation). For OpenAI-style N→N batch embedding, loop client-side: send one request per item. Returns the OpenAI-compatible envelope (`object: "list"`, `data: [{ embedding, index, object }]`, `model`, `usage`) plus the Aurous `usage` extension carrying `credits_charged` and a per-modality `breakdown` (`input: { text, visual, video }`) so you can correlate charge to input. `credits_charged` is authoritative. `Idempotency-Key` is always honored. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/embeddings 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_` 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: post: tags: - Embeddings summary: Create embeddings description: >- Create embeddings from text and/or visual content (images, video). Multimodal input is combined into a SINGLE embedding (the underlying model concatenates parts into one document representation). For OpenAI-style N→N batch embedding, loop client-side: send one request per item. Returns the OpenAI-compatible envelope (`object: "list"`, `data: [{ embedding, index, object }]`, `model`, `usage`) plus the Aurous `usage` extension carrying `credits_charged` and a per-modality `breakdown` (`input: { text, visual, video }`) so you can correlate charge to input. `credits_charged` is authoritative. `Idempotency-Key` is always honored. operationId: V1EmbeddingsController_create parameters: - name: Idempotency-Key in: header description: >- Stripe-style idempotency key. Replays return the cached response with `Aurous-Idempotent-Replayed: true`. Same key + different canonical body returns 409 `idempotency_key_in_use`. Replay window is 24 hours. required: false schema: type: string - 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/CreateEmbeddingDto' responses: '200': description: Embedding created. content: application/json: schema: $ref: '#/components/schemas/EmbeddingResponse' 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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' Aurous-Idempotent-Replayed: description: >- Present (literal `true`) when this response was served from a stored idempotent replay — the same `Idempotency-Key` + canonical body was seen within the 24h window and the original response is returned WITHOUT re-executing (no second charge, no second task). Absent on the first (fresh) execution and on any request sent without an `Idempotency-Key`. Only on the idempotency-aware create routes. schema: type: string enum: - 'true' example: 'true' '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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' '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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' '402': description: 'Insufficient team credit balance. code: `balance_too_low`.' 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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' '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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' '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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' '429': description: >- Request-per-minute (RPM) or token-per-minute (TPM) rate limit exceeded. codes: `too_many_requests`, `tpm_rate_limit_exceeded`. 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' X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: >- Provider returned an unexpected error. code: `embeddings_provider_unknown_error`. 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 X-RateLimit-TPM-Limit: description: >- Tokens-per-minute bucket capacity for this endpoint class. Only set on TPM-throttled routes (/v1/chat/completions, /v1/embeddings). schema: type: integer example: 100000 X-RateLimit-TPM-Remaining: description: >- Tokens remaining in the current minute bucket after this request. Clamped to 0 in the header (deductions can push the internal bucket negative for one burst). schema: type: integer example: 87500 X-RateLimit-TPM-Reset: description: ISO 8601 timestamp when the TPM bucket resets to full. schema: type: string format: date-time example: '2026-05-19T18:14:00.000Z' security: - api-key: [] components: schemas: CreateEmbeddingDto: 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: the underlying model concatenates batched text into a single embedding, so a customer expecting OpenAI-style N→N would get one combined vector. Loop client-side or pass a multimodal-parts array (returns one combined embedding). 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 request returns 400 `embeddings_unsupported_dimensions`. example: 1024 encoding_format: type: string enum: - float - base64 default: float description: >- Vector encoding format. Accepted for OpenAI SDK compatibility (the Node SDK sends `base64` by default); v1 always returns `float` vectors regardless of the value sent. `base64` support (returning base64-encoded float buffers) is reserved for a future release. user: type: string description: >- End-user identifier for your records (optional). Stored on the inference row; no Aurous-side behavior. Mirrors OpenAI compat. maxLength: 256 required: - model - input EmbeddingResponse: type: object properties: object: type: string enum: - list description: OpenAI envelope discriminator. data: description: Embedding items. Always a single-element array on v1. type: array items: $ref: '#/components/schemas/EmbeddingItem' model: type: string description: Model slug used for this request (echoed from the request). example: aurous-embed-vision-1.0 usage: description: Token + credit accounting for this request. allOf: - $ref: '#/components/schemas/EmbeddingUsage' required: - object - data - model - usage 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 EmbeddingItem: type: object properties: index: type: number description: >- Position of this embedding in the response array. Always 0 on v1 (one embedding per request). example: 0 object: type: string enum: - embedding description: Discriminator for OpenAI SDK compatibility. embedding: description: >- Embedding vector. Length depends on the model (e.g. 2048 for aurous-embed-vision-1.0). example: - 0.0123 - -0.0456 - 0.0789 type: array items: type: number required: - index - object - embedding EmbeddingUsage: type: object properties: prompt_tokens: type: number description: >- Total input tokens charged across all modalities (text + image + video). example: 7000 total_tokens: type: number description: Equal to prompt_tokens for embeddings (no output tokens). example: 7000 credits_charged: type: number description: >- Credits debited from your team for this request. Authoritative — the breakdown components are a reconciled decomposition of this value, scaled when an overdraft fallback fires (rare). example: 0.19125 breakdown: description: >- Per-modality credit decomposition of `credits_charged`. The `input.{text, visual, video}` fields reconcile with `credits_charged` within rounding tolerance. allOf: - $ref: '#/components/schemas/EmbeddingUsageBreakdown' required: - prompt_tokens - total_tokens - credits_charged - breakdown 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 EmbeddingUsageBreakdown: type: object properties: input: description: Per-modality credit decomposition of the total charge. allOf: - $ref: '#/components/schemas/EmbeddingUsageBreakdownInput' model: type: string description: >- Model slug used to compute the rates (matches the request `model` echoed on the response). example: aurous-embed-vision-1.0 required: - input - model EmbeddingUsageBreakdownInput: type: object properties: text: type: number description: >- Credits billed for text-token input. 0 when no text content was present in the request. example: 0.09375 visual: type: number description: >- Credits billed for visual (image) input. 0 when no image_url content was present in the request. example: 0.0975 video: type: number description: >- Credits billed 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_`). ````