API reference · v2

Files

Upload inputs and download outputs.

Create an upload

POSThttps://api.34.181.188.80.sslip.io/v2/files

Registers a file and returns an upload URL. Send the bytes with PUT to upload.url (with upload.headers), then call POST /v2/files/{id}/complete. Large files can be sent in chunks with Content-Range.

Supports the Idempotency-Key header: retrying with the same key returns the original result.

Headers

  • Idempotency-Keystring

    Retrying with the same key returns the original job instead of creating a new one (8–100 chars).

    8–100 characters

Request body application/json

  • mimestringrequired

    MIME type of the file (e.g. audio/mpeg, video/mp4, image/png)

    3–120 characters
  • bytesintegerrequired

    Exact file size in bytes

    ≥ 1
  • namestring
    1–200 characters
  • purposestring
    One ofinputreferencefirst_framelast_framedocument
    Default"input"

Responses

201Success
  • fileobjectrequired
    ShowHide child attributes
    • idstringrequired
    • objectstringrequired
      Always "file"
    • kindstringrequired
    • statusstringrequired
      One ofpendingreadyrejected
    • namestring | nullrequired
    • mimestringrequired
    • bytesintegerrequired
    • duration_msinteger | nullrequired
    • widthinteger | nullrequired
    • heightinteger | nullrequired
    • sourcestringrequired
    • job_idstring | nullrequired
    • created_atstringrequired
    • expires_atstring | nullrequired
    • download_urlstring | nullrequired

      Signed URL valid for 15 minutes; null unless the file is ready

    • download_expires_atstring | nullrequired
  • uploadobjectrequired
    ShowHide child attributes
    • urlstringrequired
    • methodstringrequired
      Always "PUT"
    • headersmaprequired
    • resumablebooleanrequired
    • chunk_bytesinteger | nullrequired
    • expires_atstringrequired
4XXClient errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

5XXServer errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

POST /v2/files
curl -X POST https://api.34.181.188.80.sslip.io/v2/files \
  -H "Authorization: Bearer $VOISER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a8f5f167-0e4c-4bde-9b6e-1c2d3e4f5a6b' \
  -d '{
    "mime": "audio/mpeg",
    "bytes": 482133
  }'
Response
{
  "file": {
    "id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
    "object": "file",
    "kind": "audio",
    "status": "pending",
    "name": "Example",
    "mime": "audio/mpeg",
    "bytes": 482133,
    "duration_ms": 14350,
    "width": 1,
    "height": 1,
    "source": "upload",
    "job_id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
    "created_at": "2026-11-17T10:24:31.000Z",
    "expires_at": "2026-11-17T10:24:31.000Z",
    "download_url": "https://files.example.com/output.mp3?expires=1763375071&signature=…",
    "download_expires_at": null
  },
  "upload": {
    "url": "https://files.example.com/output.mp3?expires=1763375071&signature=…",
    "method": "PUT",
    "headers": {},
    "resumable": false,
    "chunk_bytes": 1,
    "expires_at": "2026-11-17T10:24:31.000Z"
  }
}

Complete an upload

POSThttps://api.34.181.188.80.sslip.io/v2/files/{file_id}/complete

Verifies the uploaded bytes (type, size, duration). The file becomes ready or rejected.

Path parameters

  • file_idstringrequired

Responses

200Success
  • idstringrequired
  • objectstringrequired
    Always "file"
  • kindstringrequired
  • statusstringrequired
    One ofpendingreadyrejected
  • namestring | nullrequired
  • mimestringrequired
  • bytesintegerrequired
  • duration_msinteger | nullrequired
  • widthinteger | nullrequired
  • heightinteger | nullrequired
  • sourcestringrequired
  • job_idstring | nullrequired
  • created_atstringrequired
  • expires_atstring | nullrequired
  • download_urlstring | nullrequired

    Signed URL valid for 15 minutes; null unless the file is ready

  • download_expires_atstring | nullrequired
4XXClient errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

5XXServer errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

POST /v2/files/{file_id}/complete
curl -X POST https://api.34.181.188.80.sslip.io/v2/files/0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50/complete \
  -H "Authorization: Bearer $VOISER_API_KEY"
Response
{
  "id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
  "object": "file",
  "kind": "audio",
  "status": "pending",
  "name": "Example",
  "mime": "audio/mpeg",
  "bytes": 482133,
  "duration_ms": 14350,
  "width": 1,
  "height": 1,
  "source": "upload",
  "job_id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
  "created_at": "2026-11-17T10:24:31.000Z",
  "expires_at": "2026-11-17T10:24:31.000Z",
  "download_url": "https://files.example.com/output.mp3?expires=1763375071&signature=…",
  "download_expires_at": null
}

Import a file from a URL

POSThttps://api.34.181.188.80.sslip.io/v2/files/import

Downloads audio or video from a public link (direct file, YouTube, social media). Free; runs as a job whose result has file_id.

Supports the Idempotency-Key header: retrying with the same key returns the original result.

Returns 202 with a job. Poll it or pass webhook_url to get a webhook when it finishes.

Headers

  • Idempotency-Keystring

    Retrying with the same key returns the original job instead of creating a new one (8–100 chars).

    8–100 characters

Request body application/json

  • urlstring (uri)required
    up to 2,000 characters
  • namestring
    1–200 characters
  • webhook_urlstring

    Public https URL notified when the job finishes (see Webhooks)

    up to 2,000 characters

Responses

202Success
  • idstringrequired

    Job id

  • objectstringrequired
    Always "job"
  • operationstringrequired

    Operation that created the job (e.g. text_to_speech)

  • statusstringrequired
    One ofqueuedrunningsucceededfailedcanceled
  • progressintegerrequired
    0 to 100
  • creditsobjectrequired
    ShowHide child attributes
    • estimatedintegerrequired
    • chargedinteger | nullrequired
  • resultmap | nullrequired

    Operation-specific result; null until the job succeeds

  • filesarray of objectsrequired

    Files produced by the job; get a download URL from GET /v2/files/{id}

    ShowHide child attributes
    • idstringrequired
    • rolestringrequired
    • indexintegerrequired
  • errorobject | nullrequired
    ShowHide child attributes
    • codestringrequired
    • messagestringrequired
    • detailsmaprequired
  • created_atstringrequired
  • started_atstring | nullrequired
  • completed_atstring | nullrequired
4XXClient errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

5XXServer errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

POST /v2/files/import
curl -X POST https://api.34.181.188.80.sslip.io/v2/files/import \
  -H "Authorization: Bearer $VOISER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a8f5f167-0e4c-4bde-9b6e-1c2d3e4f5a6b' \
  -d '{
    "url": "https://files.example.com/output.mp3?expires=1763375071&signature=…"
  }'
Response
{
  "id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
  "object": "job",
  "operation": "text_to_speech",
  "status": "queued",
  "progress": 0,
  "credits": {
    "estimated": 120,
    "charged": null
  },
  "result": null,
  "files": [
    {
      "id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
      "role": "output",
      "index": 1
    }
  ],
  "error": null,
  "created_at": "2026-11-17T10:24:31.000Z",
  "started_at": null,
  "completed_at": null
}

Get a file and its download URL

GEThttps://api.34.181.188.80.sslip.io/v2/files/{file_id}

Path parameters

  • file_idstringrequired

Responses

200Success
  • idstringrequired
  • objectstringrequired
    Always "file"
  • kindstringrequired
  • statusstringrequired
    One ofpendingreadyrejected
  • namestring | nullrequired
  • mimestringrequired
  • bytesintegerrequired
  • duration_msinteger | nullrequired
  • widthinteger | nullrequired
  • heightinteger | nullrequired
  • sourcestringrequired
  • job_idstring | nullrequired
  • created_atstringrequired
  • expires_atstring | nullrequired
  • download_urlstring | nullrequired

    Signed URL valid for 15 minutes; null unless the file is ready

  • download_expires_atstring | nullrequired
4XXClient errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

5XXServer errorerror object
  • errorobjectrequired
    ShowHide child attributes
    • codestringrequired

      Stable machine-readable error code

    • messagestringrequired
    • detailsmaprequired
    • request_idstring | nullrequired

      Quote this when contacting support

GET /v2/files/{file_id}
curl https://api.34.181.188.80.sslip.io/v2/files/0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50 \
  -H "Authorization: Bearer $VOISER_API_KEY"
Response
{
  "id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
  "object": "file",
  "kind": "audio",
  "status": "pending",
  "name": "Example",
  "mime": "audio/mpeg",
  "bytes": 482133,
  "duration_ms": 14350,
  "width": 1,
  "height": 1,
  "source": "upload",
  "job_id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
  "created_at": "2026-11-17T10:24:31.000Z",
  "expires_at": "2026-11-17T10:24:31.000Z",
  "download_url": "https://files.example.com/output.mp3?expires=1763375071&signature=…",
  "download_expires_at": null
}