Schemas¶

This page documents the key data models used in the Backend API. For the complete schema reference, see the OpenAPI specification.

Core Models¶

MediaResource¶

A content-addressable media file tracked by the platform. All new uploads are stored at canonical paths (media/{resource_id}/file.{ext}) with automatic deduplication via content hash.

{
  "id": "uuid",
  "resource_type": "IMAGE | VIDEO",
  "url": "string (full CDN URL)",
  "content_hash": "string (MD5)",
  "extension": "string",
  "file_size": "integer",
  "width": "integer | null",
  "height": "integer | null",
  "aspect_ratio": "float | null",
  "orientation": "portrait | landscape | square | null",
  "dominant_color": "string | null",
  "protected": "boolean",
  "alt_text": "string | null",
  "caption": "string | null",
  "color_profile": "string | null (images only)",
  "duration": "float | null (videos only)"
}

MediaResourceAttachment¶

Polymorphic join record linking a MediaResource to an owning entity.

{
  "entity_type": "PRODUCT | SUBJECT | PREDICTION | ...",
  "entity_id": "uuid",
  "slot": "string (e.g. cover_image, reference_images)",
  "position": "integer | null (null for single slots, index for list slots)"
}

MediaInput¶

Input schema for media fields in create/update requests. Exactly one of url or media_resource_id must be provided.

{
  "url": "string | null (presigned temp URL for new upload)",
  "media_resource_id": "uuid | null (reuse existing resource)",
  "width": "integer | null",
  "height": "integer | null"
}

See MediaResource Lifecycle for the full data model.

Brand¶

Represents a customer organization.

{
  "id": "uuid",
  "name": "string",
  "slug": "string",
  "logo_url": "string | null",
  "settings": {
    "default_style_id": "uuid | null",
    "default_resolution_preset_id": "uuid | null"
  },
  "created_at": "datetime",
  "updated_at": "datetime"
}

Product¶

A catalog item to be photographed. Product images are tracked via MediaResourceAttachment (slots: cover_image, back_image, reference_images). API responses include MediaResourcePublic objects alongside legacy URL strings during the migration period.

{
  "id": "uuid",
  "brand_id": "uuid",
  "name": "string",
  "sku": "string | null",
  "category": "string",
  "cover_image": "MediaResourcePublic | null",
  "back_image": "MediaResourcePublic | null",
  "reference_images": ["MediaResourcePublic"],
  "cover_image_url": "string | null (legacy)",
  "back_image_url": "string | null (legacy)",
  "metadata": {},
  "created_at": "datetime",
  "updated_at": "datetime"
}

Shooting¶

A photo shoot session containing multiple looks.

{
  "id": "uuid",
  "brand_id": "uuid",
  "name": "string",
  "status": "draft | active | completed | archived",
  "looks_count": "integer",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Shot¶

An individual deliverable image.

{
  "id": "uuid",
  "shooting_look_id": "uuid",
  "shot_type_id": "uuid",
  "status": "pending | generating | review | approved | rejected",
  "current_image_url": "string | null",
  "revisions": [
    {
      "id": "uuid",
      "image_url": "string",
      "created_at": "datetime"
    }
  ],
  "created_at": "datetime",
  "updated_at": "datetime"
}

Generation Models¶

Subject¶

An AI model identity with consistent appearance.

{
  "id": "uuid",
  "brand_id": "uuid",
  "name": "string",
  "description": "string | null",
  "reference_images": ["string"],
  "embedding_id": "string | null",
  "metadata": {},
  "created_at": "datetime"
}

Style¶

Visual aesthetic definition for generations.

{
  "id": "uuid",
  "name": "string",
  "description": "string | null",
  "reference_images": ["string"],
  "prompt_modifiers": "string | null",
  "parameters": {
    "lighting": "string | null",
    "color_grading": "string | null"
  },
  "created_at": "datetime"
}

Generation¶

An image generation task.

{
  "id": "uuid",
  "shot_id": "uuid",
  "status": "pending | processing | completed | failed",
  "config": {
    "model_id": "uuid",
    "seed": "integer | null",
    "steps": "integer",
    "guidance_scale": "float"
  },
  "predictions": ["Prediction"],
  "error": "string | null",
  "created_at": "datetime",
  "completed_at": "datetime | null"
}

Prediction¶

A single generated image result.

{
  "id": "uuid",
  "generation_id": "uuid",
  "image_url": "string",
  "seed": "integer",
  "metadata": {
    "model": "string",
    "inference_time_ms": "integer"
  },
  "created_at": "datetime"
}

Common Patterns¶

Pagination¶

List endpoints return paginated responses:

{
  "items": [],
  "total": 100,
  "page": 1,
  "size": 20,
  "pages": 5
}

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`size`	integer	20	Items per page (max 100)

Timestamps¶

All timestamps use ISO 8601 format in UTC:

2024-01-15T10:30:00Z

UUIDs¶

All resource IDs are UUIDs (v4):

550e8400-e29b-41d4-a716-446655440000

Nullable Fields¶

Fields that can be null are indicated with | null in the type. When creating/updating, omit the field or pass null explicitly.

Enums¶

Shooting Status¶

Value	Description
`draft`	Initial state, not started
`active`	In progress, accepting looks
`completed`	All looks finished
`archived`	Archived for reference

Shot Status¶

Value	Description
`pending`	Awaiting generation
`generating`	Generation in progress
`review`	Ready for review
`approved`	Accepted as final
`rejected`	Rejected, may retry

Generation Status¶

Value	Description
`pending`	Queued for processing
`processing`	Currently generating
`completed`	Successfully finished
`failed`	Error occurred

Validation Errors¶

When request validation fails, the API returns a 422 response:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    },
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Field	Description
`loc`	Path to the invalid field
`msg`	Human-readable error message
`type`	Error type identifier