feature/api-development #1
|
|
@ -22,6 +22,57 @@ Project is in active development with no existing clients. All changes can be ma
|
|||
- Service methods
|
||||
- API documentation
|
||||
|
||||
### 1.2 Reference Images Auto-Detection
|
||||
|
||||
**Parameter behavior:**
|
||||
- `referenceImages` parameter is **optional**
|
||||
- If provided (array of aliases or IDs) → use these images as references
|
||||
- If empty or not provided → service must automatically parse prompt and find all aliases
|
||||
|
||||
**Auto-detection logic:**
|
||||
|
||||
1. **Prompt parsing:**
|
||||
- Scan prompt text for all alias patterns (@name)
|
||||
- Extract all found aliases
|
||||
- Resolve each alias to actual image ID
|
||||
|
||||
2. **Manual override:**
|
||||
- If `referenceImages` parameter is provided and not empty → use only specified images
|
||||
- Manual list takes precedence over auto-detected aliases
|
||||
|
||||
3. **Combined approach:**
|
||||
- If `referenceImages` provided → add to auto-detected aliases (merge)
|
||||
- Remove duplicates
|
||||
- Maintain order: manual references first, then auto-detected
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
// Auto-detection (no referenceImages parameter)
|
||||
{
|
||||
"prompt": "A landscape based on @sunset with elements from @mountain"
|
||||
// System automatically detects @sunset and @mountain
|
||||
}
|
||||
|
||||
// Manual specification
|
||||
{
|
||||
"prompt": "A landscape",
|
||||
"referenceImages": ["@sunset", "image-uuid-123"]
|
||||
// System uses only specified images
|
||||
}
|
||||
|
||||
// Combined
|
||||
{
|
||||
"prompt": "A landscape based on @sunset",
|
||||
"referenceImages": ["@mountain"]
|
||||
// System uses both @mountain (manual) and @sunset (auto-detected)
|
||||
}
|
||||
```
|
||||
|
||||
**Implementation notes:**
|
||||
- Alias detection must use the same validation rules as alias creation
|
||||
- Invalid aliases in prompt should be logged but not cause generation failure
|
||||
- Maximum reference images limit still applies after combining manual + auto-detected
|
||||
|
||||
---
|
||||
|
||||
## 2. Enhanced Prompt Support - Logic Redesign
|
||||
|
|
@ -364,7 +415,7 @@ After: flow.aliases = { "@product": "img-456" }
|
|||
- If `outputImage.alias !== null` → keep image, delete only generation
|
||||
- If `outputImage.alias === null` → delete both image and generation
|
||||
|
||||
**Rationale:**
|
||||
**Rationale:**
|
||||
- Image with project alias is used as standalone asset, preserve it
|
||||
- Image without alias was created only for this generation, delete together
|
||||
|
||||
|
|
@ -396,7 +447,7 @@ After: flow.aliases = { "@product": "img-456" }
|
|||
- Images without alias → DELETE (with MinIO cleanup)
|
||||
- Images with project alias → KEEP (unlink: flowId = NULL)
|
||||
|
||||
**Rationale:**
|
||||
**Rationale:**
|
||||
Flow deletion removes all content except images with project aliases (used globally in project).
|
||||
|
||||
### 7.4 Transactional Delete Pattern
|
||||
|
|
@ -780,6 +831,58 @@ Response: { "flowId": "my-flow-uuid", ... }
|
|||
|
||||
---
|
||||
|
||||
## 12. Code Documentation Standards
|
||||
|
||||
### 12.1 Endpoint JSDoc Comments
|
||||
|
||||
**Requirement:** Every API endpoint must have comprehensive JSDoc comment.
|
||||
|
||||
**Required sections:**
|
||||
|
||||
1. **Purpose:** What this endpoint does (one sentence)
|
||||
2. **Logic:** Brief description of how it works (2-3 key steps)
|
||||
3. **Parameters:** Description of each parameter and what it affects
|
||||
4. **Authentication:** Required authentication level
|
||||
5. **Response:** What is returned
|
||||
|
||||
**Example format:**
|
||||
```typescript
|
||||
/**
|
||||
* Generate new image from text prompt with optional reference images.
|
||||
*
|
||||
* Logic:
|
||||
* 1. Parse prompt to auto-detect reference image aliases
|
||||
* 2. Resolve all aliases (auto-detected + manual) to image IDs
|
||||
* 3. Trigger AI generation with prompt and reference images
|
||||
* 4. Store result with metadata and return generation record
|
||||
*
|
||||
* @param {string} prompt - Text description for image generation (affects: output style and content)
|
||||
* @param {string[]} referenceImages - Optional aliases/IDs for reference images (affects: visual style transfer)
|
||||
* @param {string} aspectRatio - Image dimensions ratio (affects: output dimensions, default: 1:1)
|
||||
* @param {string} flowId - Optional flow association (affects: organization and flow-scoped aliases)
|
||||
* @param {string} alias - Optional project-scoped alias (affects: image referencing across project)
|
||||
* @param {string} flowAlias - Optional flow-scoped alias (affects: image referencing within flow)
|
||||
* @param {boolean} autoEnhance - Enable AI prompt enhancement (affects: prompt quality and detail)
|
||||
* @param {object} meta - Custom metadata (affects: searchability and organization)
|
||||
*
|
||||
* @authentication Project Key required
|
||||
* @returns {GenerationResponse} Generation record with status and output image details
|
||||
*/
|
||||
router.post('/generations', ...);
|
||||
```
|
||||
|
||||
**Apply to:**
|
||||
- All route handlers in `/routes/**/*.ts`
|
||||
- All public service methods that implement core business logic
|
||||
- Complex utility functions with non-obvious behavior
|
||||
|
||||
**Parameter descriptions must include "affects:"**
|
||||
- Explain what each parameter influences in the system
|
||||
- Help developers understand parameter impact
|
||||
- Make API more discoverable and self-documenting
|
||||
|
||||
---
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
### Database Changes
|
||||
|
|
@ -790,15 +893,16 @@ Response: { "flowId": "my-flow-uuid", ... }
|
|||
|
||||
### API Changes
|
||||
1. Rename parameters: assignAlias → alias, assignFlowAlias → flowAlias
|
||||
2. Rename endpoint: POST /generations/:id/retry → /generations/:id/regenerate
|
||||
3. Remove endpoint: POST /api/v1/flows (no longer needed)
|
||||
4. Add endpoint: POST /api/v1/flows/:id/regenerate
|
||||
5. Add endpoint: PUT /api/v1/generations/:id (modification)
|
||||
6. Add CDN endpoints:
|
||||
2. Make referenceImages parameter optional with auto-detection from prompt
|
||||
3. Rename endpoint: POST /generations/:id/retry → /generations/:id/regenerate
|
||||
4. Remove endpoint: POST /api/v1/flows (no longer needed)
|
||||
5. Add endpoint: POST /api/v1/flows/:id/regenerate
|
||||
6. Add endpoint: PUT /api/v1/generations/:id (modification)
|
||||
7. Add CDN endpoints:
|
||||
- GET /cdn/:org/:project/img/:filenameOrAlias (all images)
|
||||
- GET /cdn/:org/:project/live/:scope (live URLs)
|
||||
7. Add scope management endpoints (CRUD for live_scopes)
|
||||
8. Update all image URLs in API responses to use CDN format
|
||||
8. Add scope management endpoints (CRUD for live_scopes)
|
||||
9. Update all image URLs in API responses to use CDN format
|
||||
|
||||
### Behavior Changes
|
||||
1. Lazy flow creation (create on second request or when flowAlias present)
|
||||
|
|
@ -809,9 +913,15 @@ Response: { "flowId": "my-flow-uuid", ... }
|
|||
6. Cascade delete for flows (with alias protection)
|
||||
7. Live URL caching and scope management
|
||||
8. FlowId in responses (generate if undefined, keep if null)
|
||||
9. Auto-detect reference images from prompt aliases
|
||||
|
||||
### Validation Changes
|
||||
1. @ symbol distinguishes aliases from UUIDs
|
||||
2. Technical aliases forbidden in user input
|
||||
3. Flow creation on-the-fly for non-existent flowIds
|
||||
4. Scope format validation for live URLs
|
||||
|
||||
### Documentation Changes
|
||||
1. Add comprehensive JSDoc comments to all endpoints
|
||||
2. Include purpose, logic, parameters with "affects" descriptions
|
||||
3. Document authentication requirements in comments
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ X-API-Key: {{apiKey}}
|
|||
"prompt": "A modern lorry truck driving on a winding mountain road during sunset, the truck has a large @logo-snail prominently displayed on its side panel, photorealistic style, golden hour lighting, detailed commercial vehicle, scenic mountain landscape",
|
||||
"aspectRatio": "16:9",
|
||||
"referenceImages": ["@logo-snail"],
|
||||
"assignAlias": "@lorry-branded",
|
||||
"assignAlias": "@lorry",
|
||||
"autoEnhance": false
|
||||
}
|
||||
|
||||
|
|
@ -78,6 +78,21 @@ X-API-Key: {{apiKey}}
|
|||
@lorryGenerationId = {{generateLorry.response.body.$.data.id}}
|
||||
@lorryImageId = {{generateLorry.response.body.$.data.outputImageId}}
|
||||
|
||||
### new
|
||||
POST {{base}}/api/v1/generations
|
||||
Content-Type: application/json
|
||||
X-API-Key: {{apiKey}}
|
||||
|
||||
{
|
||||
"prompt": "Грузовик @lorry стоит на разгрузке в аэропорту рядом с огромным грузовым самолетом на фоне гор",
|
||||
"aspectRatio": "16:9",
|
||||
"referenceImages": ["@lorry"],
|
||||
"assignAlias": "@airplane",
|
||||
"autoEnhance": false
|
||||
}
|
||||
|
||||
###
|
||||
|
||||
|
||||
###############################################################################
|
||||
# VERIFICATION: Check Both Generations
|
||||
|
|
@ -92,7 +107,7 @@ X-API-Key: {{apiKey}}
|
|||
|
||||
### Resolve @lorry-branded Alias
|
||||
# Confirm the lorry image alias is assigned
|
||||
GET {{base}}/api/v1/images/resolve/@lorry-branded
|
||||
GET {{base}}/api/v1/images/resolve/@lorry
|
||||
X-API-Key: {{apiKey}}
|
||||
|
||||
###
|
||||
|
|
|
|||
Loading…
Reference in New Issue