{"openapi":"3.0.0","paths":{"/v1/loras":{"get":{"description":"Returns all LoRA styles available to your team, including public LoRAs and any privately delivered to your team.","operationId":"V1Controller_listLoras","parameters":[],"responses":{"200":{"description":"List of available LoRA styles","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LoraResponse"}}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"security":[{"api-key":[]}],"summary":"List available LoRA styles","tags":["Public API (v1)"]}},"/v1/loras/{id}":{"get":{"description":"Returns details for a single LoRA style including its name, description, default weight, and tags.","operationId":"V1Controller_getLoraById","parameters":[{"name":"id","required":true,"in":"path","description":"LoRA UUID","schema":{"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}}],"responses":{"200":{"description":"LoRA details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoraResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"LoRA not found"}},"security":[{"api-key":[]}],"summary":"Get a LoRA style by ID","tags":["Public API (v1)"]}},"/v1/generations":{"post":{"description":"Submits an image generation request. Credits are deducted immediately from your team balance. The generation is processed asynchronously — poll GET /v1/generations/:id to check status, or provide a `webhook_url` to receive a POST callback when the generation completes or fails. The webhook payload contains `{ event: \"generation.completed\"|\"generation.failed\", data: {...} }` where `data` has the same shape as the GET /v1/generations/:id response. Delivery is attempted up to 3 times with a 2-second delay between retries. Provide a `lora_id` (from GET /v1/loras). Use size presets (e.g. \"hd_square\") or specify custom width/height. \n\n**Note on prompt processing:** the platform may apply additional preprocessing configured per LoRA before dispatching to the underlying model. Outputs may therefore reflect more than just your raw `prompt`. The `enhance_prompt` flag controls only the optional LLM rewriting step; other preprocessing is non-configurable from the public API.","operationId":"V1Controller_createGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGenerationDto"}}}},"responses":{"201":{"description":"Generation created and queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResponse"}}}},"400":{"description":"Bad request - validation failed or missing lora_id"},"401":{"description":"Unauthorized - invalid or missing API key"},"402":{"description":"Insufficient credits"}},"security":[{"api-key":[]}],"summary":"Create a new image generation","tags":["Public API (v1)"]},"get":{"description":"Returns a paginated list of your team's image generations, ordered by creation date (newest first).","operationId":"V1Controller_listGenerations","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page (max 100)","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"Paginated list of generations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationListResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"security":[{"api-key":[]}],"summary":"List your generation history","tags":["Public API (v1)"]}},"/v1/generations/{id}":{"get":{"description":"Returns the current status and details of a generation. Poll this endpoint to track async generation progress.","operationId":"V1Controller_getGeneration","parameters":[{"name":"id","required":true,"in":"path","description":"Generation ID","schema":{"example":"42","type":"string"}}],"responses":{"200":{"description":"Generation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Generation not found"}},"security":[{"api-key":[]}],"summary":"Get a single generation by ID","tags":["Public API (v1)"]}},"/v1/generations/{id}/cancel":{"post":{"description":"Cancels a generation that has not yet completed. Credits are refunded if the generation was still pending or processing.","operationId":"V1Controller_cancelGeneration","parameters":[{"name":"id","required":true,"in":"path","description":"Generation ID to cancel","schema":{"example":"42","type":"string"}}],"responses":{"200":{"description":"Generation cancelled and credits refunded"},"400":{"description":"Generation cannot be cancelled (already completed or failed)"},"401":{"description":"Unauthorized - invalid or missing API key"},"404":{"description":"Generation not found"}},"security":[{"api-key":[]}],"summary":"Cancel a pending or processing generation","tags":["Public API (v1)"]}},"/v1/video-loras":{"get":{"description":"Returns all video LoRA models available to your team for video generation.","operationId":"V1Controller_listVideoLoras","parameters":[],"responses":{"200":{"description":"List of video LoRA models","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VideoLoraResponse"}}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"security":[{"api-key":[]}],"summary":"List available video LoRA models","tags":["Public API (v1)"]}},"/v1/video-loras/{id}":{"get":{"description":"Returns details for a single video LoRA model.","operationId":"V1Controller_getVideoLoraById","parameters":[{"name":"id","required":true,"in":"path","description":"Video LoRA UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Video LoRA details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoLoraResponse"}}}},"404":{"description":"Video LoRA not found"}},"security":[{"api-key":[]}],"summary":"Get a video LoRA model by ID","tags":["Public API (v1)"]}},"/v1/video-generations":{"post":{"description":"Submits a video generation request using BytePlus Seedance. Credits are deducted based on video duration. Supports text-to-video (prompt only) and image-to-video (first frame, or first+last frame). Poll GET /v1/generations/:id to check status or provide a webhook_url.","operationId":"V1Controller_createVideoGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVideoGenerationDto"}}}},"responses":{"201":{"description":"Video generation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResponse"}}}},"400":{"description":"Validation failed"},"402":{"description":"Insufficient credits"}},"security":[{"api-key":[]}],"summary":"Create a new video generation","tags":["Public API (v1)"]}},"/v1/team":{"get":{"description":"Returns basic information about the team associated with this API key, including the current credit balance.","operationId":"V1Controller_getTeam","parameters":[],"responses":{"200":{"description":"Team information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"security":[{"api-key":[]}],"summary":"Get your team info","tags":["Public API (v1)"]}},"/v1/usage":{"get":{"description":"Returns usage statistics for the team associated with this API key, broken down by the specified interval.","operationId":"V1Controller_getUsage","parameters":[],"responses":{"200":{"description":"Usage analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"security":[{"api-key":[]}],"summary":"Get usage analytics","tags":["Public API (v1)"]}},"/v1/balance":{"get":{"description":"Returns the current credit balance for the team associated with this API key.","operationId":"V1Controller_getBalance","parameters":[],"responses":{"200":{"description":"Current credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key"}},"security":[{"api-key":[]}],"summary":"Get credit balance","tags":["Public API (v1)"]}}},"info":{"title":"Aurous Labs API","description":"Generate AI images with custom LoRA styles.\n\n## Authentication\nAll requests require an API key passed in the `X-Api-Key` header.\nCreate API keys in your [dashboard](https://app.aurous-labs.com/dashboard/api-keys).\n\n## Quick Start\n```bash\ncurl -X POST https://api.aurous-labs.com/v1/generations \\\n  -H \"X-Api-Key: og_your_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"A golden sunset over mountains\", \"lora_id\": \"your-lora-id\", \"size\": \"hd_square\"}'\n```","version":"1.0.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Your team API key (starts with og_)"}},"schemas":{"LoraResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique LoRA identifier (UUID)","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","description":"Display name of the LoRA style","example":"Golden Hour Photography"},"description":{"type":"string","description":"Description of the LoRA style and its effects","example":"Adds warm golden-hour lighting with soft lens flares"},"preview_image_url":{"type":"string","description":"URL of the LoRA preview image","example":"https://cdn.aurous-labs.com/previews/golden-hour.jpg"},"is_public":{"type":"boolean","description":"Whether this LoRA is publicly available","example":true},"default_weight":{"type":"number","description":"Default weight applied to this LoRA (0.1-1.5)","example":0.8,"minimum":0.1,"maximum":1.5},"category":{"type":"string","description":"Category of the LoRA style","example":"photography"},"tags":{"description":"Tags for filtering and search","example":["lighting","warm","cinematic"],"type":"array","items":{"type":"string"}},"is_bundle":{"type":"boolean","description":"Whether this is a LoRA bundle (multiple LoRAs combined)","example":false},"has_template":{"type":"boolean","description":"Whether this LoRA has a prompt template","example":true},"created_at":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2026-03-01T00:00:00Z"}},"required":["id","name","is_public","default_weight","created_at"]},"CreateGenerationDto":{"type":"object","properties":{"prompt":{"type":"string","description":"The text prompt describing the image to generate","example":"A golden sunset over mountains, cinematic lighting, 8k resolution"},"negative_prompt":{"type":"string","description":"Negative prompt - elements to exclude from the generated image","example":"blurry, low quality, watermark, text"},"lora_id":{"type":"string","description":"UUID of the LoRA style to apply (from GET /v1/loras). Required.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"width":{"type":"number","description":"Output image width in pixels (ignored if size preset is set)","example":1024,"minimum":256,"maximum":4096},"height":{"type":"number","description":"Output image height in pixels (ignored if size preset is set)","example":1024,"minimum":256,"maximum":4096},"steps":{"type":"number","description":"Number of diffusion steps (higher = more detail, slower)","example":30,"minimum":1,"maximum":100},"guidance_scale":{"type":"number","description":"Guidance scale - how closely to follow the prompt (higher = more literal)","example":7.5,"minimum":0.1,"maximum":30},"seed":{"type":"number","description":"Random seed for reproducible generations. Omit for random.","example":42},"size":{"type":"string","description":"Size preset for the output image. Overrides width/height if set.","example":"hd_square","enum":["square","landscape","portrait","hd_square","hd_landscape","hd_portrait"]},"count":{"type":"number","description":"Number of images to generate in this request","example":1,"minimum":1,"maximum":4},"enhance_prompt":{"type":"boolean","description":"When true, an LLM rewrites your prompt before generation using the LoRA's style template. This is the only customer-facing prompt-shaping toggle in the public API. Pricing: enhanced generations cost a configurable multiplier of the base rate.","example":false},"webhook_url":{"type":"string","description":"Optional webhook URL. When provided, a POST request will be sent to this URL when the generation completes or fails. The payload contains an `event` field (\"generation.completed\" or \"generation.failed\") and a `data` field with the generation details (same shape as GET /v1/generations/:id). Delivery is attempted up to 3 times with a 2-second delay between retries.","example":"https://your-server.com/webhooks/aurouslabs"},"reference_image_url":{"type":"string","description":"Optional reference image URL for image-to-image generation. When provided, the generation uses the reference image as a starting point. The denoise_strength parameter controls how much the output deviates from the reference (0.01 = near-copy, 1.0 = ignore reference).","example":"https://example.com/reference.jpg"},"denoise_strength":{"type":"number","description":"Denoise strength for image-to-image generation. Controls how much the output deviates from the reference image. Only used when reference_image_url is provided.","example":0.6,"minimum":0.01,"maximum":1}},"required":["prompt","lora_id"]},"GenerationResponse":{"type":"object","properties":{"id":{"type":"number","description":"Unique generation ID","example":42},"status":{"type":"string","description":"Current generation status","example":"completed","enum":["pending","processing","completed","failed","cancelled"]},"prompt":{"type":"string","description":"The text prompt used for generation","example":"A golden sunset over mountains, cinematic lighting"},"negative_prompt":{"type":"string","description":"Negative prompt to exclude from generation","example":"blurry, low quality"},"output_urls":{"description":"Generated image URLs","example":["https://cdn.aurous-labs.com/outputs/abc123.png"],"type":"array","items":{"type":"string"}},"error_message":{"type":"string","description":"Error message if the generation failed","example":"Content policy violation"},"duration_ms":{"type":"number","description":"Processing duration in milliseconds","example":15000},"cost":{"type":"number","description":"Credits consumed for this generation","example":1},"width":{"type":"number","description":"Image width in pixels","example":1024},"height":{"type":"number","description":"Image height in pixels","example":1024},"created_at":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2026-03-15T12:00:00Z"},"updated_at":{"type":"string","description":"Last update timestamp (ISO 8601)","example":"2026-03-15T12:00:15Z"}},"required":["id","status","prompt","cost","width","height","created_at"]},"GenerationListResponse":{"type":"object","properties":{"data":{"description":"List of generations","type":"array","items":{"$ref":"#/components/schemas/GenerationResponse"}},"page":{"type":"number","description":"Current page number","example":1},"limit":{"type":"number","description":"Items per page","example":20},"total":{"type":"number","description":"Total number of generations","example":150}},"required":["data","page","limit","total"]},"VideoLoraResponse":{"type":"object","properties":{"id":{"type":"string","description":"Video LoRA UUID","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"name":{"type":"string","description":"Display name","example":"Seedance 1.0 Pro"},"description":{"type":"string","description":"Description"},"preview_video_url":{"type":"string","description":"Preview video URL"},"is_public":{"type":"boolean","description":"Whether this is a public video LoRA"},"default_resolution":{"type":"string","description":"Default resolution","example":"1080p"},"default_ratio":{"type":"string","description":"Default aspect ratio","example":"16:9"},"default_duration":{"type":"number","description":"Default video duration in seconds","example":5},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","name","is_public","default_resolution","default_ratio","default_duration","created_at"]},"CreateVideoGenerationDto":{"type":"object","properties":{"prompt":{"type":"string","description":"Text prompt describing the video. Optional — enhances the generation when provided.","example":"A golden sunset over the ocean with gentle waves"},"video_lora_id":{"type":"string","description":"UUID of the video LoRA model to use","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"first_frame_url":{"type":"string","description":"URL of the first frame image. Optional — omit for text-to-video, supply for image-to-video, supply both first_frame_url and last_frame_url for first+last frame interpolation."},"last_frame_url":{"type":"string","description":"URL of the last frame image for first+last frame video generation"},"resolution":{"type":"string","description":"Output video resolution","enum":["480p","720p","1080p"]},"ratio":{"type":"string","description":"Output video aspect ratio","enum":["16:9","4:3","1:1","3:4","9:16","21:9"]},"duration":{"type":"number","description":"Video duration in seconds (2-12)","example":5,"minimum":2,"maximum":12},"seed":{"type":"number","description":"Random seed (-1 for random)"},"camera_fixed":{"type":"boolean","description":"Whether to fix the camera position"},"watermark":{"type":"boolean","description":"Whether to add watermark"},"enhance_prompt":{"type":"boolean","description":"Whether to enhance the prompt with AI"},"webhook_url":{"type":"string","description":"Webhook URL to receive POST callback when generation completes or fails"}},"required":["video_lora_id"]},"TeamResponse":{"type":"object","properties":{"id":{"type":"number","description":"Unique team ID","example":1},"name":{"type":"string","description":"Team display name","example":"Acme Studio"},"credits":{"type":"number","description":"Current credit balance","example":500},"billing_email":{"type":"string","description":"Billing email address","example":"billing@acme.com"},"created_at":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2026-01-15T00:00:00Z"}},"required":["id","name","credits","created_at"]},"UsagePeriodEntry":{"type":"object","properties":{"period":{"type":"string","description":"Period label (date or range)","example":"2026-03-01"},"generations":{"type":"number","description":"Number of generations in this period","example":42},"credits_used":{"type":"number","description":"Credits consumed in this period","example":42}},"required":["period","generations","credits_used"]},"UsageResponse":{"type":"object","properties":{"data":{"description":"Usage breakdown by period","type":"array","items":{"$ref":"#/components/schemas/UsagePeriodEntry"}},"total_generations":{"type":"number","description":"Total generations across all periods","example":350},"total_credits_used":{"type":"number","description":"Total credits consumed across all periods","example":350}},"required":["data","total_generations","total_credits_used"]},"BalanceResponse":{"type":"object","properties":{"credits":{"type":"number","description":"Current credit balance for the team","example":500}},"required":["credits"]}}}}