aymara_ai.resources.files

aymara_ai.resources.files#

Classes#

FilesResource

AsyncFilesResource

Module Contents#

class aymara_ai.resources.files.FilesResource(client)[source]#

Bases: aymara_ai._resource.SyncAPIResource

Parameters:

client (aymara_ai._client.AymaraAI)

property with_raw_response: FilesResourceWithRawResponse#

This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.

For more information, see https://www.github.com/aymara-ai/aymara-sdk-python#accessing-raw-response-data-eg-headers

Return type:

FilesResourceWithRawResponse

property with_streaming_response: FilesResourceWithStreamingResponse#

An alternative to .with_raw_response that doesn’t eagerly read the response body.

For more information, see https://www.github.com/aymara-ai/aymara-sdk-python#with_streaming_response

Return type:

FilesResourceWithStreamingResponse

create(*, files, workspace_uuid=omit, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Request upload URLs for one or more files.

Use this for batch uploads or when uploading files hosted at remote URLs.

Args: upload_request (FileUploadRequest): Contains files to upload and workspace UUID. - Set remote_uri to fetch files from external URLs - Set local_file_path to generate an upload URL for client-side uploads

Returns: FileUploadResponse: For each file, includes: - file_uuid: Use this to reference the file in eval runs - file_url: Upload URL (PUT your file here) or download URL (for remote_uri files) - processing_status: “pending” for remote files or videos, “completed” otherwise

Example: POST /api/files { “workspace_uuid”: “…”, “files”: [ {“local_file_path”: “data.csv”}, {“remote_uri”: “https://example.com/file.mp4”} ] }

Parameters:

  • files (Iterable[aymara_ai.types.file_create_params.File]) – List of files to upload.

  • workspace_uuid (Optional[str] | aymara_ai._types.Omit) – UUID of the workspace to associate with the upload, if any.

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

Return type:

aymara_ai.types.file_create_response.FileCreateResponse

list(*, file_type=omit, limit=omit, offset=omit, workspace_uuid=omit, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

List all files for the authenticated organization, with optional filtering.

Args: workspace_uuid (str, optional): Filter by workspace UUID. file_type (str, optional): Filter by file type (image, video, text, document).

Returns: list[FileDetail]: List of files matching the filters.

Raises: AymaraAPIError: If the organization is missing.

Example: GET /api/v2/files?workspace_uuid=…&file_type=image

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_type (Optional[str] | aymara_ai._types.Omit)

  • limit (int | aymara_ai._types.Omit)

  • offset (int | aymara_ai._types.Omit)

  • workspace_uuid (Optional[str] | aymara_ai._types.Omit)

Return type:

aymara_ai.pagination.SyncOffsetPage[aymara_ai.types.file_detail.FileDetail]

delete(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Delete a file (soft delete).

Args: file_uuid (str): UUID of the file to delete.

Returns: None (204 No Content)

Raises: AymaraAPIError: If the file is not found or user lacks access.

Example: DELETE /api/v2/files/{file_uuid}

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

None

get(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Retrieve file metadata and access URL.

Args: file_uuid (str): UUID of the file to retrieve.

Returns: FileDetail: File metadata including: - file_url: Use this URL to download/view the file (valid for 30 minutes) - file_type: “image”, “video”, “text”, or “document” - processing_status: For videos, check if “completed” before accessing frames - video_metadata: Contains frame_count and other video-specific info

Note: For videos, use GET /files/{file_uuid}/frames to access individual frames.

Example: GET /api/v2/files/{file_uuid}

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

aymara_ai.types.file_detail.FileDetail

get_frames(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Get download URLs for all extracted frames from a video file.

Only available for video files after processing completes. Check processing status with GET /files/{file_uuid}/status first.

Args: file_uuid (str): UUID of the video file.

Returns: FileFramesResponse: Contains: - frame_urls: List of URLs to access each frame (sorted by frame number) - frame_count: Total number of frames available

Each frame URL is valid for 30 minutes. Use these URLs to download or display individual video frames for analysis.

Raises: AymaraAPIError: - If file is not a video (use file_type field to check) - If processing not complete (check processing_status first)

Example: GET /api/v2/files/{file_uuid}/frames

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

aymara_ai.types.file_frames.FileFrames

get_status(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Check processing status for a file.

Use this to poll video processing progress.

Args: file_uuid (str): UUID of the file to check status for.

Returns: FileStatusResponse: Contains: - processing_status: “pending”, “processing”, “completed”, or “failed” - error_message: If status is “failed”, contains error details - remote_file_path: Available when status is “completed”

Use this endpoint to poll until processing_status == “completed” before calling GET /files/{file_uuid}/frames for video files.

Example: GET /api/v2/files/{file_uuid}/status

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

aymara_ai.types.file_status.FileStatus

upload(*, file, workspace_uuid=omit, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Upload a file directly in the request body.

Use this for single file uploads from your application.

For video files, processing happens asynchronously - use GET /files/{file_uuid}/status to check processing status before accessing frames.

Args: file: The file to upload (multipart form data) workspace_uuid: Optional workspace to associate the file with

Returns: FileUploadResult with file_uuid for future reference and file_url for immediate access. For videos, check processing_status field - use status endpoint to poll until “completed”.

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file (aymara_ai._types.FileTypes)

  • workspace_uuid (Optional[str] | aymara_ai._types.Omit)

Return type:

aymara_ai.types.file_upload.FileUpload

class aymara_ai.resources.files.AsyncFilesResource(client)[source]#

Bases: aymara_ai._resource.AsyncAPIResource

Parameters:

client (aymara_ai._client.AsyncAymaraAI)

property with_raw_response: AsyncFilesResourceWithRawResponse#

This property can be used as a prefix for any HTTP method call to return the raw response object instead of the parsed content.

For more information, see https://www.github.com/aymara-ai/aymara-sdk-python#accessing-raw-response-data-eg-headers

Return type:

AsyncFilesResourceWithRawResponse

property with_streaming_response: AsyncFilesResourceWithStreamingResponse#

An alternative to .with_raw_response that doesn’t eagerly read the response body.

For more information, see https://www.github.com/aymara-ai/aymara-sdk-python#with_streaming_response

Return type:

AsyncFilesResourceWithStreamingResponse

async create(*, files, workspace_uuid=omit, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Request upload URLs for one or more files.

Use this for batch uploads or when uploading files hosted at remote URLs.

Args: upload_request (FileUploadRequest): Contains files to upload and workspace UUID. - Set remote_uri to fetch files from external URLs - Set local_file_path to generate an upload URL for client-side uploads

Returns: FileUploadResponse: For each file, includes: - file_uuid: Use this to reference the file in eval runs - file_url: Upload URL (PUT your file here) or download URL (for remote_uri files) - processing_status: “pending” for remote files or videos, “completed” otherwise

Example: POST /api/files { “workspace_uuid”: “…”, “files”: [ {“local_file_path”: “data.csv”}, {“remote_uri”: “https://example.com/file.mp4”} ] }

Parameters:

  • files (Iterable[aymara_ai.types.file_create_params.File]) – List of files to upload.

  • workspace_uuid (Optional[str] | aymara_ai._types.Omit) – UUID of the workspace to associate with the upload, if any.

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

Return type:

aymara_ai.types.file_create_response.FileCreateResponse

list(*, file_type=omit, limit=omit, offset=omit, workspace_uuid=omit, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

List all files for the authenticated organization, with optional filtering.

Args: workspace_uuid (str, optional): Filter by workspace UUID. file_type (str, optional): Filter by file type (image, video, text, document).

Returns: list[FileDetail]: List of files matching the filters.

Raises: AymaraAPIError: If the organization is missing.

Example: GET /api/v2/files?workspace_uuid=…&file_type=image

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_type (Optional[str] | aymara_ai._types.Omit)

  • limit (int | aymara_ai._types.Omit)

  • offset (int | aymara_ai._types.Omit)

  • workspace_uuid (Optional[str] | aymara_ai._types.Omit)

Return type:

aymara_ai._base_client.AsyncPaginator[aymara_ai.types.file_detail.FileDetail, aymara_ai.pagination.AsyncOffsetPage[aymara_ai.types.file_detail.FileDetail]]

async delete(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Delete a file (soft delete).

Args: file_uuid (str): UUID of the file to delete.

Returns: None (204 No Content)

Raises: AymaraAPIError: If the file is not found or user lacks access.

Example: DELETE /api/v2/files/{file_uuid}

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

None

async get(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Retrieve file metadata and access URL.

Args: file_uuid (str): UUID of the file to retrieve.

Returns: FileDetail: File metadata including: - file_url: Use this URL to download/view the file (valid for 30 minutes) - file_type: “image”, “video”, “text”, or “document” - processing_status: For videos, check if “completed” before accessing frames - video_metadata: Contains frame_count and other video-specific info

Note: For videos, use GET /files/{file_uuid}/frames to access individual frames.

Example: GET /api/v2/files/{file_uuid}

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

aymara_ai.types.file_detail.FileDetail

async get_frames(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Get download URLs for all extracted frames from a video file.

Only available for video files after processing completes. Check processing status with GET /files/{file_uuid}/status first.

Args: file_uuid (str): UUID of the video file.

Returns: FileFramesResponse: Contains: - frame_urls: List of URLs to access each frame (sorted by frame number) - frame_count: Total number of frames available

Each frame URL is valid for 30 minutes. Use these URLs to download or display individual video frames for analysis.

Raises: AymaraAPIError: - If file is not a video (use file_type field to check) - If processing not complete (check processing_status first)

Example: GET /api/v2/files/{file_uuid}/frames

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

aymara_ai.types.file_frames.FileFrames

async get_status(file_uuid, *, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Check processing status for a file.

Use this to poll video processing progress.

Args: file_uuid (str): UUID of the file to check status for.

Returns: FileStatusResponse: Contains: - processing_status: “pending”, “processing”, “completed”, or “failed” - error_message: If status is “failed”, contains error details - remote_file_path: Available when status is “completed”

Use this endpoint to poll until processing_status == “completed” before calling GET /files/{file_uuid}/frames for video files.

Example: GET /api/v2/files/{file_uuid}/status

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file_uuid (str)

Return type:

aymara_ai.types.file_status.FileStatus

async upload(*, file, workspace_uuid=omit, extra_headers=None, extra_query=None, extra_body=None, timeout=not_given)[source]#

Upload a file directly in the request body.

Use this for single file uploads from your application.

For video files, processing happens asynchronously - use GET /files/{file_uuid}/status to check processing status before accessing frames.

Args: file: The file to upload (multipart form data) workspace_uuid: Optional workspace to associate the file with

Returns: FileUploadResult with file_uuid for future reference and file_url for immediate access. For videos, check processing_status field - use status endpoint to poll until “completed”.

Parameters:

  • extra_headers (aymara_ai._types.Headers | None) – Send extra headers

  • extra_query (aymara_ai._types.Query | None) – Add additional query parameters to the request

  • extra_body (aymara_ai._types.Body | None) – Add additional JSON properties to the request

  • timeout (float | httpx.Timeout | None | aymara_ai._types.NotGiven) – Override the client-level default timeout for this request, in seconds

  • file (aymara_ai._types.FileTypes)

  • workspace_uuid (Optional[str] | aymara_ai._types.Omit)

Return type:

aymara_ai.types.file_upload.FileUpload

Contents