Request signed upload URL (recommended)

Viewing v1— superseded by v2

POST

/v1/workspaces/{workspace_id}/files/upload-url

curl --request POST \
  --url https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "content_type": "<string>",
  "file_name": "<string>",
  "file_size_bytes": 0,
  "source_type": "pose"
}'

import requests

url = "https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url"

payload = {
    "content_type": "<string>",
    "file_name": "<string>",
    "file_size_bytes": 0,
    "source_type": "pose"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

const url = 'https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"content_type":"<string>","file_name":"<string>","file_size_bytes":0,"source_type":"pose"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url"

  payload := strings.NewReader("{\n  \"content_type\": \"<string>\",\n  \"file_name\": \"<string>\",\n  \"file_size_bytes\": 0,\n  \"source_type\": \"pose\"\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content_type' => '<string>',
    'file_name' => '<string>',
    'file_size_bytes' => 0,
    'source_type' => 'pose'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"content_type\": \"<string>\",\n  \"file_name\": \"<string>\",\n  \"file_size_bytes\": 0,\n  \"source_type\": \"pose\"\n}");
Request request = new Request.Builder()
  .url("https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

require 'uri'
require 'net/http'

url = URI("https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content_type\": \"<string>\",\n  \"file_name\": \"<string>\",\n  \"file_size_bytes\": 0,\n  \"source_type\": \"pose\"\n}"

response = http.request(request)
puts response.read_body

var client = new RestClient("https://api.app.layer.ai/api/v1/workspaces/:workspace_id/files/upload-url");
var request = new RestRequest("", Method.Post);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"content_type\": \"<string>\",\n  \"file_name\": \"<string>\",\n  \"file_size_bytes\": 0,\n  \"source_type\": \"pose\"\n}", ParameterType.RequestBody);
var response = client.Execute(request);

v1 is superseded. v1 was superseded by v2 on 2026-08-26. A sunset date has not been announced yet; v1 will be deprecated as a whole before removal. Migrate with the v2 migration guide.

Get a signed URL to upload a file directly to storage, bypassing the server. This is the recommended upload method for large files.

Flow:

Call this endpoint with content_type and file_size_bytes
POST to the returned upload_url with header x-goog-resumable: start to get a session URI
PUT your file content to the session URI (supports chunked/resumable uploads)
Use the returned file_id as input to generation endpoints

Allowed types: application/x-zip-compressed, application/zip, audio/mpeg, audio/wav, font/otf, font/ttf, image/heic, image/heic-sequence, image/heif, image/heif-sequence, image/jpeg, image/png, image/webp, model/gltf-binary, video/mp4. Max size: 100 MB for video, meshes and zip bundles, 64 MB for images and audio, 16 MB for fonts. Upload URL expires in 15 minutes.

Authorizations

bearerAuth
oauth2
serviceAccount
library:write

Parameters

Path Parameters

workspace_id

required

Workspace Id

Id of the workspace that owns the resource.

string format: uuid

Id of the workspace that owns the resource.

Header Parameters

Idempotency-Key

string

<= 255 characters

Opaque key making a retry of this request return the first result. A 2xx response is replayed for 24 hours with Idempotent-Replayed: true. A 4xx releases the key. A 5xx, or a request still running, holds the key for 120 seconds, during which a retry gets 409; after that a retry executes again. The key covers the method, path, query, and byte-identical body it was first used with; reusing it for a different request is rejected with 422. Protection is best effort: if the key store is unavailable, or a record is lost early, a retry can execute again even after an earlier 409. See the Idempotency section of the API description.

Request Body^required

application/json

RequestUploadUrlRequest

object

content_type

required

Content Type

MIME type of the file to upload.

string

file_name

File Name

Optional file name.

string

nullable

file_size_bytes

required

File Size Bytes

Expected file size in bytes. Used to enforce upload limits.

integer

> 0

source_type

Any of:

FileSourceType
null

FileSourceType

string

Allowed values: pose reference mask composite google_drive miro transformed_reference skill_resource skill_bundle

Responses

201

Successful Response

application/json

RequestUploadUrlResponse

object

file_id

required

File Id

Unique identifier for the file. Use as input to generation endpoints after upload completes.

string format: uuid

upload_url

required

Upload Url

Signed upload URL. POST to this URL to initiate a resumable upload, then PUT file chunks to the session URI returned in the Location header. Expires in 15 minutes.

string

content_type

required

Content Type

MIME type to use when uploading.

string

source_type

Any of:

FileSourceType
null

FileSourceType

string

Allowed values: pose reference mask composite google_drive miro transformed_reference skill_resource skill_bundle

Example

{
  "source_type": "pose"
}

401

Unauthenticated — missing or invalid Bearer token.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

403

Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

404

Resource not found.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

409

The outcome of the request with this Idempotency-Key is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in Retry-After.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

422

Invalid input parameters, or an Idempotency-Key reused for a different request.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

429

Rate limited — retry after the number of seconds in Retry-After.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

500

Internal server error.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

Request signed upload URL (recommended)

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

Request Body^required