> ## 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. # Upload a reference file > 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`/`reference_audio_url` fields on POST /v1/videos — duration (2–15 s) and, for video, frame area (409,600–2,073,600 px) are validated at upload, so a stored file never fails media checks at create. 24h TTL — the file is auto-purged after that. The response carries a 1h signed URL; re-mint a fresh URL via GET /v1/files/:id. Multipart form with a `file` (binary) part, plus form fields `purpose` and optional `metadata` (JSON-encoded object, <=50 keys, values <=500 chars). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/files 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/files: post: tags: - Public API (v1) summary: Upload a reference file description: >- 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`/`reference_audio_url` fields on POST /v1/videos — duration (2–15 s) and, for video, frame area (409,600–2,073,600 px) are validated at upload, so a stored file never fails media checks at create. 24h TTL — the file is auto-purged after that. The response carries a 1h signed URL; re-mint a fresh URL via GET /v1/files/:id. Multipart form with a `file` (binary) part, plus form fields `purpose` and optional `metadata` (JSON-encoded object, <=50 keys, values <=500 chars). operationId: V1FilesController_uploadFile parameters: - name: Idempotency-Key in: header description: >- Stripe-style idempotency key (1-256 chars). Same key + same `purpose` + `metadata` returns the cached response with `Aurous-Idempotent-Replayed: true`. Same key against a different route (e.g. previously used on /v1/images) returns `409 invalid_request / idempotency_key_in_use`. Replay window is 24 hours. Absent header is treated as non-idempotent (each call processes anew). 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: multipart/form-data: schema: type: object required: - file - purpose properties: file: type: string format: binary description: >- The file bytes. Image purposes: PNG / JPEG / WebP, max 10MB, max 4096px. `reference_video`: MP4 / MOV, max 50MB, 2–15 s. `reference_audio`: WAV / MP3, max 15MB, 2–15 s. purpose: type: string enum: - reference - first_frame - last_frame - reference_video - reference_audio description: >- How the file will be used downstream. Must match the uploaded bytes (a WAV under `reference_video` is rejected). metadata: type: string description: JSON-encoded metadata object. Optional. responses: '201': description: File stored content: application/json: schema: $ref: '#/components/schemas/FileResponse' 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 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 failed (missing file, unsupported mime, dimension exceeded, etc.) 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: Unauthorized 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: >- Account not approved for closed beta. error.code is one of `account_pending`, `account_rejected`, `account_suspended`. There is no retry — contact support to be approved. 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 '409': description: >- Idempotency-Key was reused with a different request body, or was previously used on a different route (e.g. /v1/images). 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 '413': description: >- Body exceeds the 52MB transport cap (50MB video + multipart overhead) 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 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 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 security: - api-key: [] components: schemas: FileResponse: type: object properties: id: type: string example: file_01HXMQ7Z3K8Y2NABCDEFGHJKMN description: Opaque file ID. object: type: string example: file description: Object discriminator. purpose: type: string example: reference enum: - reference - first_frame - last_frame - reference_video - reference_audio description: >- How the file is used downstream. Image purposes: `reference`, `first_frame`, `last_frame`. Media purposes (PR-4): `reference_video` / `reference_audio` for the `/v1/videos` BYO reference fields. mime_type: type: string example: image/jpeg enum: - image/png - image/jpeg - image/webp - video/mp4 - video/quicktime - audio/mpeg - audio/wav size_bytes: type: number example: 1247892 description: File size in bytes. width_px: type: object example: 1024 description: Decoded image width in pixels (max 4096). nullable: true height_px: type: object example: 768 description: Decoded image height in pixels (max 4096). nullable: true duration_s: type: number example: 7.4 description: >- Clip duration in seconds — populated for media uploads (`reference_video` / `reference_audio`, parsed at upload time), `null` for images. nullable: true url: type: string example: https://...?token=... description: >- Time-limited signed URL valid for ~1h. Re-mint a fresh URL by re-fetching GET /v1/files/:id. Do NOT cache long-term — the underlying bucket is private. expires_at: type: string example: '2026-05-04T14:00:00Z' description: Hard 24h TTL — the file is automatically purged at this timestamp. metadata: type: object example: campaign: launch-2026 description: Echoed metadata. additionalProperties: type: string created_at: type: string example: '2026-05-03T14:00:00Z' description: Creation timestamp. required: - id - object - purpose - mime_type - size_bytes - width_px - height_px - url - expires_at - created_at ErrorResponse: type: object properties: error: description: Error payload allOf: - $ref: '#/components/schemas/ErrorPayload' required: - error 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 - style_retired - parameter_invalid - 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 securitySchemes: api-key: type: apiKey in: header name: X-Api-Key description: Your team API key (starts with `al_live_`). ````