Docs/API/Frames

Frames API

Upload and manage reference images (frames) for your projects. Frames are used as exemplars for training taste profiles.

Supported Formats

File Types

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
GIF (.gif)

Limits

Max file size: 10 MB
Max batch upload: 20 files

GET/api/frames

List all frames for a project. Requires project ownership or annotator access.

Query Parameters

Parameter	Type	Description
projectId	string	Required. The project to list frames from

Request

curl "https://api.commandAGI.com/api/frames?projectId=proj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "frames": [
    {
      "id": "frm_abc123",
      "url": "https://cdn.commandAGI.com/frames/proj_abc123/image1.jpg",
      "filename": "image1.jpg",
      "contentType": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "frm_def456",
      "url": "https://cdn.commandAGI.com/frames/proj_abc123/image2.png",
      "filename": "image2.png",
      "contentType": "image/png",
      "width": 2560,
      "height": 1440,
      "createdAt": "2024-01-15T10:35:00Z"
    }
  ]
}

POST/api/frames/upload

Upload a single frame to a project. The frame is stored in Vercel Blob storage.

Request Body (multipart/form-data)

Field	Type	Description
file	File	Required. The image file to upload
projectId	string	Required. The project to upload to

Request

curl -X POST https://api.commandAGI.com/api/frames/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "projectId=proj_abc123" \
  -F "file=@/path/to/image.jpg"

Response

{
  "success": true,
  "frame": {
    "id": "frm_ghi789",
    "url": "https://cdn.commandAGI.com/frames/proj_abc123/image.jpg",
    "filename": "image.jpg"
  }
}

PUT/api/frames/upload

Upload multiple frames at once. Files that fail validation are reported in the errors array.

Request Body (multipart/form-data)

Field	Type	Description
files	File[]	Required. Multiple image files to upload
projectId	string	Required. The project to upload to

Request

curl -X PUT https://api.commandAGI.com/api/frames/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "projectId=proj_abc123" \
  -F "files=@image1.jpg" \
  -F "files=@image2.jpg" \
  -F "files=@image3.png"

Response

{
  "success": true,
  "uploaded": [
    {
      "id": "frm_001",
      "url": "https://cdn.commandAGI.com/frames/proj_abc123/image1.jpg",
      "filename": "image1.jpg"
    },
    {
      "id": "frm_002",
      "url": "https://cdn.commandAGI.com/frames/proj_abc123/image2.jpg",
      "filename": "image2.jpg"
    }
  ],
  "errors": [
    {
      "filename": "image3.png",
      "error": "File too large"
    }
  ]
}

DELETE/api/frames

Delete a frame from a project. The file is removed from blob storage and the database.

Warning: Deleting a frame removes it permanently. If the frame was used as an exemplar in a taste profile, the profile may need to be retrained.

Query Parameters

Parameter	Type	Description
frameId	string	Required. The ID of the frame to delete

Request

curl -X DELETE "https://api.commandAGI.com/api/frames?frameId=frm_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true
}

Error Codes

Code	Error	Description
`400`	Invalid file type	File must be JPEG, PNG, WebP, or GIF
`400`	File too large	Maximum file size is 10MB
`400`	No file provided	Request must include a file
`403`	Access denied	User does not own the project
`404`	Project not found	The specified project does not exist

Profiles API Evaluation API