Play VoiceFileUpload

Project: Pet Feeder | page_id: 1753

Device Alarm Audio Upload API Document (Server-Side Integration)

Overview

• Base path: /api
• API name: Device alarm audio upload
• Path: /api/device/upload/alarm-file
• Method: POST
• Content-Type: multipart/form-data
• Authentication: request header X-Token
• Handler: deviceH.UploadAlarmFile

Authentication Header

Common Authentication Failure Response

{
  "code": 401,
  "msg": "Not logged in or session expired",
  "data": null
}

{
  "code": 401,
  "msg": "Login expired, please log in again",
  "data": null
}

2. Intended Audience

This document is intended for server-side API callers and App/H5/admin backend integration personnel.

You only need to call the server-side API. There is no need to request the device local address directly, and no need to generate device signature parameters yourself.

3. Function Description

The client uploads an audio file, and the server forwards it to the alarm audio upload API of the specified device.

The server reads the uploaded file stream and passes it through to the device as multipart/form-data without writing it to local disk first.

4. Request Parameters

The request body uses multipart/form-data.

5. Request Example

curl --request POST "http://localhost:8080/api/device/upload/alarm-file" \
  --header "X-Token: <token>" \
  --form "deviceId=dev_001" \
  --form "times=3" \
  --form "file=@./alarm.wav"

6. Parameter Validation Rules

• deviceId cannot be empty.
• When times is not provided, the default value is 1.
• file must be uploaded.

7. Response Description

This API passes through the device response content and HTTP status code.

7.1 Success Response Example

{
  "code": 0,
  "msg": "ok"
}

7.2 Common Failure Responses

Missing parameter:

{
  "code": 400,
  "msg": "deviceId cannot be empty",
  "data": null
}

Invalid times:

{
  "code": 400,
  "msg": "times must be an integer",
  "data": null
}

Missing file:

{
  "code": 400,
  "msg": "Please upload a file",
  "data": null
}

When the device connection fails, the server returns 502 with an error message.

8. Integration Notes

• The caller only needs to care about the server-side API /api/device/upload/alarm-file.
• The real device address and the signature parameters t and token are all handled automatically by the server.
• In the current implementation, times participates in the final assembly of the device-side command.

9. Code Location

• Route registration: cmd/main.go
• Handler: internal/handler/device_handler.go
• Forwarding logic: internal/clouds/cloud_request.go

10. Device-Side Implementation Reference

In-site Docs Center