API

Save a workspace material

Generated from the checked-in source. Do not edit this reference by hand.

POST /api/v1/workspaces/{workspace}/assets

Member Write permission required. Raw binary body with exact supported Content-Type and required name query; no multipart or base64 envelope. Authentication and a bounded upload slot precede body collection. Original bytes are immutable, encrypted with workspace/asset identity binding, limited to 8 MiB each and 256 MiB/256 active objects per workspace. Images undergo bounded pixel decoding; audio/video undergo local frame/container structural validation. This is not content-inspection approval, Provider upload, licensing evidence or inference authorization. Repeated uploads create distinct objects; uncertain clients should reconcile the library before repeating. The server resolves the organization from the authorized workspace. Foreign or missing workspaces return 404. The compatibility route remains supported with identical payload, owner, revision and replay semantics.

Operation: uploadWorkspaceAssetByWorkspace.

Authentication

Use the credential and permission scope described above. Each object below is an alternative; schemes within one object are required together.

[
  {
    "bearerAuth": []
  }
]

HTTP request

Set NIU_ORIGIN to your installation origin (without /v1). Replace path, query and header placeholders with the required values. Query examples use curl 7.87 or newer to encode values with --url-query. Use the credential scope described above; a bearer token must have the authority required by this operation.

curl --fail-with-body -X POST "$NIU_ORIGIN/api/v1/workspaces/{workspace}/assets" \
  -H "Authorization: Bearer $NIU_BEARER_TOKEN" \
  --url-query 'name=<NAME>' \
  -H 'Content-Type: image/png' \
  --data-binary @request-body

Parameters

workspace

Location: path. Required.

{
  "type": "string",
  "format": "uuid"
}

name

Location: query. Required. Trimmed nonblank name; at most 200 UTF-8 bytes after trimming; no control characters.

{
  "type": "string",
  "minLength": 1,
  "maxLength": 200
}

Request body

image/png

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

image/jpeg

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

image/webp

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

video/mp4

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

video/webm

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

audio/wav

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

audio/mpeg

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

audio/ogg

Required.

{
  "type": "string",
  "format": "binary",
  "minLength": 1,
  "maxLength": 8388608
}

Responses

HTTP 201

Scoped asset metadata; no private ciphertext or actor identifier.

Content type: application/json.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "name",
        "media_kind",
        "content_type",
        "content_sha256",
        "byte_length",
        "revision",
        "created_at_ms",
        "updated_at_ms"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Internal routing reference; never display as a user label."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Trimmed display name, at most 200 UTF-8 bytes, without control characters."
        },
        "media_kind": {
          "type": "string",
          "enum": [
            "image",
            "video",
            "audio"
          ]
        },
        "content_type": {
          "type": "string",
          "enum": [
            "image/png",
            "image/jpeg",
            "image/webp",
            "video/mp4",
            "video/webm",
            "audio/wav",
            "audio/mpeg",
            "audio/ogg"
          ]
        },
        "content_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "SHA-256 of the immutable original bytes."
        },
        "byte_length": {
          "type": "integer",
          "minimum": 1,
          "maximum": 8388608
        },
        "revision": {
          "type": "string",
          "pattern": "^[1-9][0-9]*$",
          "description": "Canonical positive signed-64-bit integer; use for rename/delete concurrency checks."
        },
        "created_at_ms": {
          "type": "integer",
          "format": "int64"
        },
        "updated_at_ms": {
          "type": "integer",
          "format": "int64"
        },
        "source": {
          "type": [
            "object",
            "null"
          ],
          "description": "Authorized original generation context. Null when absent or not visible to this actor; sharing a retained copy does not grant source access.",
          "additionalProperties": false,
          "required": [
            "reference",
            "kind",
            "output",
            "model",
            "created_at"
          ],
          "properties": {
            "reference": {
              "type": "string",
              "pattern": "^run-[1-9][0-9]{0,18}$"
            },
            "kind": {
              "const": "video"
            },
            "output": {
              "enum": [
                "video",
                "last_frame"
              ]
            },
            "model": {
              "type": "string"
            },
            "created_at": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    }
  }
}

HTTP 400

Malformed query/body, unsupported type, invalid media bytes, name, page size or revision.

HTTP 401

Missing/invalid member administrator authentication; inference keys do not manage materials.

HTTP 403

Authenticated principal lacks workspace scope or required Read/Write permission.

HTTP 404

Workspace or scoped active asset not found.

HTTP 409

Stale revision, unavailable cursor or serialized workspace quota exceeded.

HTTP 413

Raw body exceeds 8 MiB.

HTTP 503

Bounded processing capacity, encryption or storage unavailable; no successful write is confirmed.

Behavior and supported scope

Supported scope: implemented