# Aurous Labs ## Docs - [Create a character](https://docs.aurous-labs.com/api-reference/characters/create-character.md): Upload existing ref images or synthesize 4 ref poses from a description. - [Delete a character](https://docs.aurous-labs.com/api-reference/characters/delete-character.md): Cancel-review a reviewing character or soft-delete any other state. - [List characters](https://docs.aurous-labs.com/api-reference/characters/list-characters.md): Page through your team's characters, newest first. - [Regenerate a single ref pose](https://docs.aurous-labs.com/api-reference/characters/regenerate-ref.md): Re-run synthesis for one pose without re-doing the other three. - [Resynthesize a character](https://docs.aurous-labs.com/api-reference/characters/resynthesize-character.md): Re-run the synthesize pipeline to produce a fresh set of refs. - [Retrieve a character](https://docs.aurous-labs.com/api-reference/characters/retrieve-character.md): Fetch a character by ID. Use this to poll the synthesize flow. - [Save a reviewing character](https://docs.aurous-labs.com/api-reference/characters/save-character.md): Promote a synthesize-flow character from reviewing to ready. - [Update a character](https://docs.aurous-labs.com/api-reference/characters/update-character.md): Edit a character's name and attributes. Refs are immutable. - [Classify an uploaded ref](https://docs.aurous-labs.com/api-reference/characters/upload-classify.md): Detect the pose of an image you uploaded via /v1/characters/uploads/init. - [Mint a character upload URL](https://docs.aurous-labs.com/api-reference/characters/upload-init.md): Get a signed PUT URL for one character reference image. - [Cancel an in-flight chat completion](https://docs.aurous-labs.com/api-reference/chat/cancel-an-in-flight-chat-completion.md): Aborts a streaming chat completion that is still in progress. Commits actuals up to the abort point against the credit hold and releases the remainder. Returns the final-state `ChatCompletionResponse`. - [Chat cancellation](https://docs.aurous-labs.com/api-reference/chat/cancellation.md): Cancel an in-flight chat completion mid-stream via POST /v1/chat/completions/{id}/cancel. Partial-token billing semantics. - [Create a chat completion](https://docs.aurous-labs.com/api-reference/chat/create-a-chat-completion.md): OpenAI-compatible chat completion. Supports streaming (`stream: true` returns `text/event-stream` SSE), function calling (`tools` / `tool_choice`), multimodal input (image_url / video_url content parts), reasoning_effort, and structured output (`response_format`). Pricing: credits are debited from t… - [Chat idempotency](https://docs.aurous-labs.com/api-reference/chat/idempotency.md): Safe retries on POST /v1/chat/completions — replay semantics, the streaming exception, and cross-route conflict handling. - [Multimodal input](https://docs.aurous-labs.com/api-reference/chat/multimodal.md): Pass images and video alongside text in a chat completion. - [Chat completions](https://docs.aurous-labs.com/api-reference/chat/overview.md): OpenAI-compatible chat over the Aurous Labs API. Drop-in for any OpenAI SDK. - [Pricing](https://docs.aurous-labs.com/api-reference/chat/pricing.md): Credit math for chat completions, with the rate-mutability asymmetry. - [Reasoning effort](https://docs.aurous-labs.com/api-reference/chat/reasoning.md): Tune deliberate reasoning depth for reasoning-capable chat models. - [Retrieve a stored chat completion](https://docs.aurous-labs.com/api-reference/chat/retrieve-a-stored-chat-completion.md): Look up a previously created chat completion by its opaque id (`cmp_`). Returns the reconstructed `ChatCompletionResponse` with the actuals committed at completion time. Cross-team lookups return 404 (no enumeration leak). - [Streaming](https://docs.aurous-labs.com/api-reference/chat/streaming.md): Server-Sent Events for chat completions, with token usage in the final chunk. - [Structured output](https://docs.aurous-labs.com/api-reference/chat/structured-output.md): Schema-enforced JSON output from POST /v1/chat/completions via response_format. Two modes: json_schema (strict) and json_object (loose). - [Tools and function calling](https://docs.aurous-labs.com/api-reference/chat/tools.md): Define callable tools and let the model decide when to invoke them. - [Create embeddings](https://docs.aurous-labs.com/api-reference/embeddings/create-embeddings.md): 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. - [Output Dimensions](https://docs.aurous-labs.com/api-reference/embeddings/dimensions.md): When the `dimensions` parameter is supported, when it's rejected, and the storage vs recall tradeoff. - [Estimate Cost Before Embedding](https://docs.aurous-labs.com/api-reference/embeddings/estimate.md): Preview the credit charge for an embedding request without dispatching the model or deducting credits. - [Estimate embedding credits](https://docs.aurous-labs.com/api-reference/embeddings/estimate-embedding-credits.md): 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). - [Embedding limits](https://docs.aurous-labs.com/api-reference/embeddings/limits.md): Caps on parts, characters, URLs, and request size for POST /v1/embeddings. - [Multimodal embeddings](https://docs.aurous-labs.com/api-reference/embeddings/multimodal.md): Combine text and images into a single embedding that represents the whole document. - [OpenAI batch input is not supported](https://docs.aurous-labs.com/api-reference/embeddings/openai-batch-incompat.md): Why POST /v1/embeddings rejects input: ["a","b","c"] and the recommended workaround for callers coming from OpenAI. - [Embeddings](https://docs.aurous-labs.com/api-reference/embeddings/overview.md): Vector embeddings for text and multimodal content over the Aurous Labs API. OpenAI-compatible, multimodal-native. - [Pricing](https://docs.aurous-labs.com/api-reference/embeddings/pricing.md): Credit math for embeddings, with worked examples and the per-modality breakdown. - [URL fetching for image_url](https://docs.aurous-labs.com/api-reference/embeddings/url-fetching.md): How the platform fetches image URLs server-side, what gets blocked, and what happens on timeouts or 404s. - [Get a single generated image](https://docs.aurous-labs.com/api-reference/images-proxy/get-a-single-generated-image.md): Returns the generated image. Image outputs are retained for ~7 days after generation; after that the endpoint returns `410 Gone` with `code: output_expired`. If the generation never produced an output (status `failed`, `cancelled`, `moderation_rejected`, or polling-timeout `expired`), this endpoint… - [Create an image](https://docs.aurous-labs.com/api-reference/images/create-image.md): Submit an image generation. Optionally anchor identity with a character. - [Retrieve an image](https://docs.aurous-labs.com/api-reference/images/retrieve-image.md): Fetch the live state of a generation by ID. Poll this for status. - [List chat, embedding, and video models](https://docs.aurous-labs.com/api-reference/models/list-chat-embedding-and-video-models.md): Returns the catalog of chat, embedding, and video models available to your team. Shape mirrors OpenAI's `GET /v1/models` envelope (`{ object: "list", data: [...] }`) so SDK clients that already speak OpenAI drop in unchanged. Platform-specific fields (capability tags, lifecycle pointers) live under… - [API Reference](https://docs.aurous-labs.com/api-reference/openapi.md): Every Aurous Labs V1 endpoint, every parameter, every response shape. - [Aggregated usage metrics](https://docs.aurous-labs.com/api-reference/public-api-v1/aggregated-usage-metrics.md): Time-bucketed aggregates of every generation your team has dispatched. - [Cancel a pending or processing generation](https://docs.aurous-labs.com/api-reference/public-api-v1/cancel-a-pending-or-processing-generation.md): Cancels a generation that has not yet completed. Returns the cancelled generation resource. On a generation already in `cancelled` state this is a no-op (idempotent). On a generation already in `succeeded` or `failed` this returns `400 invalid_request / generation_not_cancellable` (terminal states c… - [Delete a webhook endpoint](https://docs.aurous-labs.com/api-reference/public-api-v1/delete-a-webhook-endpoint.md): Idempotent — always returns 200, never 404. The response body reports whether anything was actually removed: `{ deleted: true, id: }` when the team owned the row, `{ deleted: false, id: null }` when nothing matched (already-gone, wrong team, typo). The `id` echoed back i… - [Estimate the credit cost of a video generation](https://docs.aurous-labs.com/api-reference/public-api-v1/estimate-the-credit-cost-of-a-video-generation.md): For a fixed duration, `estimated_cost.amount` is the exact charge. For adaptive (`duration: -1`, the default), `estimated_cost.adaptive` is `true` and the price is a range: `amount_min`–`amount_max`, where `amount` equals `amount_max` (the credits held up front). You are charged for the delivered le… - [Estimate the credit cost of an image generation](https://docs.aurous-labs.com/api-reference/public-api-v1/estimate-the-credit-cost-of-an-image-generation.md): Same DTO as POST /v1/images. Returns the projected credit cost and a per-line-item breakdown (`base` + optional `enhance`) without enqueuing the work. Reference images are free and do not affect price. Inputs are validated with the same rules as the create path — a private style from another team, a… - [Fire a synthetic test delivery](https://docs.aurous-labs.com/api-reference/public-api-v1/fire-a-synthetic-test-delivery.md): Enqueues a real, signed delivery with a fixture payload to exercise the receiver. The AurousEvent envelope carries `synthetic: true` so receivers can filter test fires from production traffic. Independent rate limit bucket (`webhooks_test`, 30/min) so it does not contend with normal webhook traffic. - [Get a composition act by ID](https://docs.aurous-labs.com/api-reference/public-api-v1/get-a-composition-act-by-id.md): Resolves an id from GET /v1/actions — a cheap liveness / support check for a persisted `action_id` (an act’s `supported_character_counts` changes as its stills are approved). Returns 404 for any id that is not a live act visible to your team. - [Get a file (re-mints a fresh 1h signed URL)](https://docs.aurous-labs.com/api-reference/public-api-v1/get-a-file-re-mints-a-fresh-1h-signed-url.md): Returns the file metadata plus a freshly-minted 1h signed URL. Use this to re-mint a download URL whenever the previous one expires. - [Get a LoRA style by ID or slug](https://docs.aurous-labs.com/api-reference/public-api-v1/get-a-lora-style-by-id-or-slug.md): Resolves `lora_*` opaque IDs (canonical) or the mutable `slug`. Returns `404 not_found` if the LoRA is private to another team. - [Get a video model by ID or slug](https://docs.aurous-labs.com/api-reference/public-api-v1/get-a-video-model-by-id-or-slug.md): Resolves an id (or slug) from GET /v1/video_loras. Returns 404 for models that are not part of the catalog. - [Get a webhook endpoint](https://docs.aurous-labs.com/api-reference/public-api-v1/get-a-webhook-endpoint.md): Returns the endpoint metadata. `secret` is always null on reads. - [Get credit balance](https://docs.aurous-labs.com/api-reference/public-api-v1/get-credit-balance.md): Returns the team's credit balance broken down into total `credits`, `held_credits` (locked against pending generations on a charge-on-success basis), and `available_credits` = `credits` − `held_credits`. `POST /v1/images` and `POST /v1/videos` check against `available_credits` and return `402 invali… - [Get your team info](https://docs.aurous-labs.com/api-reference/public-api-v1/get-your-team-info.md): Returns basic information about the team associated with this API key, including the current credit balance and a `billing_mode` field. When `billing_mode` is `exempt`, do not gate on balance — generations are never blocked. Treat `billing_mode` as an open enum (unknown values ⇒ non-gating). - [Immediately purge a file](https://docs.aurous-labs.com/api-reference/public-api-v1/immediately-purge-a-file.md): Idempotent — returns 200 even when the file does not exist or has already been deleted. In-flight generations that already snapshotted the URL keep working; subsequent GET /v1/files/:id calls return 404. - [List available composition acts](https://docs.aurous-labs.com/api-reference/public-api-v1/list-available-composition-acts.md): Returns the catalog of live composition acts you can pin via `action_id` on POST /v1/images. Each act carries the subject counts it supports (`supported_character_counts`) — pin it with a matching number of subjects, or with zero subjects to render a new person your prompt describes. Selecting an ac… - [List available LoRA styles](https://docs.aurous-labs.com/api-reference/public-api-v1/list-available-lora-styles.md): Returns all LoRA styles available to your team, including public LoRAs and any privately delivered to your team. Each item carries an opaque `lora_*` ID and a URL-friendly `slug`; either form works in `/v1/loras/:id_or_slug` and in the `lora_id` field of `POST /v1/images`. - [List available video models](https://docs.aurous-labs.com/api-reference/public-api-v1/list-available-video-models.md): Returns the catalog of video models available to pin via `video_lora_id` on POST /v1/videos. Selecting a model is optional — omit `video_lora_id` to let the platform choose automatically, or to generate plain video when no model matches your prompt. - [List credit-ledger events](https://docs.aurous-labs.com/api-reference/public-api-v1/list-credit-ledger-events.md): Cursor-paginated stream of every credit movement on your team — holds placed and released or committed by your generations, top-ups via Stripe, refunds, and admin adjustments. Ordered newest-first. Use `?starting_after=` to walk older entries; `?limit=N` (1–100, default 20). Filter by `?type… - [List delivery attempts for a webhook endpoint](https://docs.aurous-labs.com/api-reference/public-api-v1/list-delivery-attempts-for-a-webhook-endpoint.md): Cursor-paged. Each row is one attempt — the same `event_id` may appear on up to 5 rows for a flapping receiver (5-attempt retry policy with exponential backoff [5s, 30s, 2m, 10m, 1h]). - [List webhook endpoints](https://docs.aurous-labs.com/api-reference/public-api-v1/list-webhook-endpoints.md): Cursor-paged. Returns endpoints in reverse chronological order (newest first). Pass `?starting_after=we_` to walk subsequent pages. - [List your generation history](https://docs.aurous-labs.com/api-reference/public-api-v1/list-your-generation-history.md): Cursor-paginated list of your team's image and video generations, ordered by creation date (newest first). Use `?starting_after=` to walk forward and `?ending_before=` to walk backward; `?limit=N` (1–100, default 20). The cursor is the opaque `id` of any row from the prior page. Internal acc… - [Register a webhook endpoint](https://docs.aurous-labs.com/api-reference/public-api-v1/register-a-webhook-endpoint.md): Mints a new endpoint, generates a signing secret, and returns the secret EXACTLY ONCE in the `secret` field. Store it on your side — subsequent reads return `secret: null`. Subscribe to `["*"]` to receive every event in the v1.0 taxonomy (the wildcard is expanded at create time; new event types adde… - [Rotate the signing secret](https://docs.aurous-labs.com/api-reference/public-api-v1/rotate-the-signing-secret.md): Mints a new plaintext, demotes the old secret to a 24h dual-validate window (receivers verify against the new first; on failure, fall back to the previous), and returns the new plaintext EXACTLY ONCE. After 24h the old secret is dropped. - [Update a webhook endpoint](https://docs.aurous-labs.com/api-reference/public-api-v1/update-a-webhook-endpoint.md): Partial update. Re-passing `events: ["*"]` snapshots the current taxonomy (same semantics as on create). Setting `is_active=true` on a previously-disabled endpoint resets `consecutive_failures` to 0. - [Upload a reference file](https://docs.aurous-labs.com/api-reference/public-api-v1/upload-a-reference-file.md): Stores a reference file for use in subsequent /v1/images or /v1/videos requests. Image purposes (`reference`, `first_frame`, `last_frame`): PNG/JPEG/WebP, max 10 MB, max 4096 px. Media purposes (`reference_video`: MP4/MOV ≤50 MB; `reference_audio`: WAV/MP3 ≤15 MB) feed the `reference_video_url`/`ref… - [Cancel or delete a task](https://docs.aurous-labs.com/api-reference/seedance/cancel-delete.md): DELETE /v1/contents/generations/tasks/{id} — cancel a queued task for a full refund, or hide a finished one. - [Create a task](https://docs.aurous-labs.com/api-reference/seedance/create-task.md): POST /v1/contents/generations/tasks — submit a Seedance video generation. Native Seedance request body, forwarded verbatim. - [Differences from the native API](https://docs.aurous-labs.com/api-reference/seedance/differences.md): The honest delta list: what the Aurous raw surface changes vs. the native Seedance video API. - [List tasks](https://docs.aurous-labs.com/api-reference/seedance/list-tasks.md): GET /v1/contents/generations/tasks — page and filter your Seedance tasks. No 7-day cutoff. - [Models & pricing](https://docs.aurous-labs.com/api-reference/seedance/models-and-pricing.md): The Seedance rate card, the token formula, and the exact-price guarantee. Billed in Aurous credits. - [Seedance raw API](https://docs.aurous-labs.com/api-reference/seedance/overview.md): Seedance video generation over the Aurous Labs API — provider-shape bodies with Aurous-native identifiers. Point the Ark SDK at Aurous by changing two lines. - [Retrieve a task](https://docs.aurous-labs.com/api-reference/seedance/retrieve-task.md): GET /v1/contents/generations/tasks/{id} — poll a Seedance task for status, result, and the settled charge. - [Per-request usage event stream](https://docs.aurous-labs.com/api-reference/usage/event-stream.md): Stream individual billed requests via GET /v1/usage/events — one row per billed call, the raw data underlying /v1/usage. - [Usage analytics](https://docs.aurous-labs.com/api-reference/usage/overview.md): Query your team usage across chat, embedding, image, and video — by status, model, API key, user, and time bucket — via GET /v1/usage. - [Usage pagination](https://docs.aurous-labs.com/api-reference/usage/pagination.md): How the GET /v1/usage cursor walk works — and the known edge case when limit is smaller than the per-bucket group count. - [Get the generated video](https://docs.aurous-labs.com/api-reference/videos-proxy/get-the-generated-video.md): Returns the generated video. Video outputs are retained for ~24 hours after generation; after that the endpoint returns `410 Gone` with `code: output_expired`. If the generation never produced an output (status `failed`, `cancelled`, `moderation_rejected`, or polling-timeout `expired`), this endpoin… - [Create a video](https://docs.aurous-labs.com/api-reference/videos/create-video.md): Submit a video generation — text-to-video, image-to-video, or subject-driven with a saved character or reference images. - [Authentication](https://docs.aurous-labs.com/authentication.md): API keys, scopes, rotation, and the 24h grace window. - [Changelog](https://docs.aurous-labs.com/changelog.md): Aurous-Version date entries with diffs. - [Errors](https://docs.aurous-labs.com/errors.md): Stable typed error envelope, 5 types, every code documented. - [Composition acts](https://docs.aurous-labs.com/guides/actions.md): Pin a ready-made composition act to POST /v1/images with action_id, browse the catalog at GET /v1/actions, and let the tri-state control automatic act detection. - [Cost transparency](https://docs.aurous-labs.com/guides/cost-transparency.md): How to read the credits_charged + breakdown story on every response, reconcile your billing, and forecast spend. - [Error handling](https://docs.aurous-labs.com/guides/error-handling.md): The Aurous error envelope, the five-type taxonomy, the retry-vs-fail decision tree, and recommended retry patterns by code class. - [How we count tokens](https://docs.aurous-labs.com/guides/how-we-count-tokens.md): Tokenizer details across text, images, and video — and where Aurous Labs token counts differ from OpenAI tiktoken. - [Choose a model](https://docs.aurous-labs.com/guides/model-comparison.md): Side-by-side comparison of aurous-grow-2.0-pro and aurous-embed-vision-1.0 — what each is for, what each costs, when to pick which. - [Drop in for OpenAI](https://docs.aurous-labs.com/guides/openai-drop-in.md): Point your existing OpenAI client at Aurous Labs in two lines. No SDK swap, no rewrite, no surprises. - [Idempotency](https://docs.aurous-labs.com/idempotency.md): Safe retries for POST /v1/images, POST /v1/videos, and POST /v1/files. - [Quickstart](https://docs.aurous-labs.com/quickstart.md): Make your first chat completion, embedding, and image in under five minutes. - [Rate limits](https://docs.aurous-labs.com/rate-limits.md): Per-team token-bucket limits on V1 endpoints. - [Webhooks](https://docs.aurous-labs.com/webhooks.md): Receive real-time events when image / video generations complete or fail, when team balance crosses a low-credit threshold, and when an endpoint auto-disables. ## OpenAPI Specs - [openapi](https://docs.aurous-labs.com/api-reference/openapi.json)