REST API

Use the REST API to manage persistent Ojin resources such as model configurations and assets.

The raw OpenAPI specification for this API is also available at openapi.gitbook.com/o/V9IIQ3Cw10PlDcbzN32h/spec/ojin-rest-api.json.

This page covers the HTTP REST API. It is separate from Ojin's realtime model APIs, which use WebSockets for streaming media. For example, for ojin/oris-portrait, see Realtime API Reference.

Authentication

Authenticated REST endpoints require an API key in the X-API-Key header.

curl https://api.ojin.ai/v1/model-configs \
  -H "X-API-Key: $OJIN_API_KEY"

For API key setup guidance, see Get your API key.

Model Configurations

Use model configurations to create and manage reusable settings for Ojin models.

model_configurations is variant-specific. To determine the correct object shape, first fetch the target model variant and read its configuration_schema, then build your model_configurations payload to match that JSON Schema.

List Model Configurations

get

Retrieves a list of Model Configurations. By default returns only organization-owned configurations. Use source='template' to retrieve template configurations instead. Supports pagination and filtering by model variant.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Query parameters

model_variant_idstringOptional

Filter model configurations by the model_variant_id.

sourcestring · enumOptional

Filter items by ownership source. Use 'org' for items owned by the user's organization, 'template' for items from the template organization. Defaults to 'org'.

Default: orgPossible values:

limitinteger · min: 1 · max: 100Optional

Number of items to return per page.

Default: 20

offsetintegerOptional

Number of items to skip for pagination.

Default: 0

Responses

200

A paginated list of model configurations.

application/json

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

get

/model-configs

GET /v1/model-configs HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "model_config_id": "123e4567-e89b-12d3-a456-426614174000",
      "organization_id": "text",
      "model_id": "text",
      "model_variant_id": "text",
      "created_by": "text",
      "title": "text",
      "model_configurations": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "created_at": "2026-05-21T07:39:52.864Z",
      "updated_at": "2026-05-21T07:39:52.864Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total_items": 150
  }
}

Create a new Model Configuration

post

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Body

Payload for creating a new Model Configuration.

titlestringRequired

model_variant_idstringRequired

Responses

201

Model Configuration created.

application/json

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

Referenced ModelVariant not found.

application/json

post

/model-configs

POST /v1/model-configs HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "title": "text",
  "model_variant_id": "text",
  "model_configurations": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "model_config_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "text",
  "model_id": "text",
  "model_variant_id": "text",
  "created_by": "text",
  "title": "text",
  "model_configurations": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

Retrieve a specific Model Configuration

get

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

model_config_idstring · uuidRequired

The unique identifier (UUID) of the Model Configuration.

Responses

200

Model Configuration details.

application/json

Represents a specific configuration of a ModelVariant.

model_config_idstring · uuidRead-onlyRequired

Server-generated unique ID.

organization_idstringRead-onlyRequired

Owning organization ID (from external IdP).

model_idstringRead-onlyRequired

ID of the parent Model, derived from the Model Variant.

model_variant_idstringRequired

ID of the ModelVariant being configured. NOT NULL.

created_bystringRead-onlyRequired

Creator's user ID (from external IdP).

titlestringRequired

Title for the configuration. NOT NULL, unique per organization_id.

created_atstring · date-timeRead-onlyRequired

Timestamp of creation. Defaults to CURRENT_TIMESTAMP.

updated_atstring · date-timeRead-onlyRequired

Timestamp of last update. Auto-updates.

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

get

/model-configs/{model_config_id}

GET /v1/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "model_config_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "text",
  "model_id": "text",
  "model_variant_id": "text",
  "created_by": "text",
  "title": "text",
  "model_configurations": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

Update an existing Model Configuration

put

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

model_config_idstring · uuidRequired

The unique identifier (UUID) of the Model Configuration.

Body

Payload for updating a Model Configuration (title and parameters only).

titlestringRequired

Responses

200

Model Configuration updated.

application/json

Represents a specific configuration of a ModelVariant.

model_config_idstring · uuidRead-onlyRequired

Server-generated unique ID.

organization_idstringRead-onlyRequired

Owning organization ID (from external IdP).

model_idstringRead-onlyRequired

ID of the parent Model, derived from the Model Variant.

model_variant_idstringRequired

ID of the ModelVariant being configured. NOT NULL.

created_bystringRead-onlyRequired

Creator's user ID (from external IdP).

titlestringRequired

Title for the configuration. NOT NULL, unique per organization_id.

created_atstring · date-timeRead-onlyRequired

Timestamp of creation. Defaults to CURRENT_TIMESTAMP.

updated_atstring · date-timeRead-onlyRequired

Timestamp of last update. Auto-updates.

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

put

/model-configs/{model_config_id}

PUT /v1/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "title": "text",
  "model_configurations": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "model_config_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "text",
  "model_id": "text",
  "model_variant_id": "text",
  "created_by": "text",
  "title": "text",
  "model_configurations": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

Delete a Model Configuration

delete

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

model_config_idstring · uuidRequired

The unique identifier (UUID) of the Model Configuration.

Query parameters

referenced_bystring · uuidOptional

Delete reference to the agent configuration.

Responses

204

Operation successful, no content to return.

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

409

Conflict - Cannot delete, referenced by AgentConfig.

application/json

delete

/model-configs/{model_config_id}

DELETE /v1/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Model Variants

Use model variant endpoints to discover public variants and retrieve the configuration_schema that defines the expected shape of model_configurations.

List all Model Variants

get

List all Model Variants. If authenticated, returns variants based on filters (defaulting to all if no filters provided). If unauthenticated, ONLY returns variants with status="public", ignoring other status filters.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Query parameters

model_idstringOptional

Filter model variants by parent model_id.

statusstringOptional

Filter by status.

tagsstring[]Optional

Filter model variants by a comma-separated list of tags (AND logic).

limitinteger · min: 1 · max: 100Optional

Number of items to return per page.

Default: 20

offsetintegerOptional

Number of items to skip for pagination.

Default: 0

Responses

200

A paginated list of model variants.

application/json

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

get

/model-variants

GET /v1/model-variants HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "model_variant_id": "ojin/oris-1.0/standard",
      "model_id": "ojin/oris-1.0",
      "title": "Standard Quality",
      "description": {
        "resolution": "1024x1024"
      },
      "preview_media_url": "https://cdn.ojin.ai/previews/variant.jpg",
      "configuration_schema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string"
          }
        }
      },
      "tags": [
        "general-purpose",
        "real-time"
      ],
      "status": "available",
      "created_at": "2026-05-21T07:39:52.864Z",
      "updated_at": "2026-05-21T07:39:52.864Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total_items": 150
  }
}

Retrieve a specific Model Variant

get

Retrieve a specific Model Variant by ID. If authenticated, returns the variant regardless of status. If unauthenticated, ONLY returns the variant if status="public". Otherwise returns 404.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

model_variant_idstringRequired

The unique identifier of the model variant.

Responses

200

Model Variant details.

application/json

Represents a specific variant of a Model.

model_variant_idstringRequired

Client-provided unique identifier (e.g., "ojin/oris-v1/standard").

Example: ojin/oris-1.0/standard

model_idstringRequired

Identifier of the parent Model. NOT NULL.

Example: ojin/oris-1.0

titlestringRequired

Display name for the variant. NOT NULL, unique per model_id.

Example: Standard Quality

preview_media_urlstring · url · nullableOptional

URL for a preview media.

Example: https://cdn.ojin.ai/previews/variant.jpg

tagsstring[]Required

List of descriptive tags. NOT NULL, defaults to '[]'.

Example: ["general-purpose","real-time"]

statusstringRequired

Status (e.g., 'available', 'deprecated'). NOT NULL. List managed in code.

Example: available

created_atstring · date-timeRead-onlyRequired

Timestamp of creation. Server-generated. Defaults to CURRENT_TIMESTAMP.

updated_atstring · date-timeRead-onlyRequired

Timestamp of last update. Server-generated. Auto-updates.

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

get

/model-variants/{model_variant_id}

GET /v1/model-variants/{model_variant_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "model_variant_id": "ojin/oris-1.0/standard",
  "model_id": "ojin/oris-1.0",
  "title": "Standard Quality",
  "description": {
    "resolution": "1024x1024"
  },
  "preview_media_url": "https://cdn.ojin.ai/previews/variant.jpg",
  "configuration_schema": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string"
      }
    }
  },
  "tags": [
    "general-purpose",
    "real-time"
  ],
  "status": "available",
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

Assets

Use asset endpoints to upload, register, retrieve, and delete media used by your Ojin integrations.

Initiate a Multipart Asset Upload

post

Starts the multipart asset upload process by creating a multipart upload session in S3. The Core API generates a unique asset_id and receives an upload_id from S3. Both IDs must be used in subsequent part signing and finalization requests. No Asset record is created in the database at this stage.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Body

Payload to initiate a multipart asset upload.

namestringRequired

Original filename of the asset.

Example: conference_highlights.mov

categorystringRequired

Category for the asset (e.g., 'video', 'image').

Example: video

content_typestring · nullableOptional

Client-declared MIME type of the file.

Example: video/quicktime

size_bytesinteger · int64 · nullableOptional

Client-declared file size in bytes.

Example: 52428800

Responses

200

Multipart upload initiated successfully. Returns asset_id and upload_id.

application/json

Response from initiating a multipart asset upload.

asset_idstring · uuidRequired

A unique ID generated by Core API for this asset transaction.

upload_idstringRequired

The multipart upload ID from S3, used to identify this multipart upload session.

s3_keystringOptional

The S3 key for this asset.

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

post

/assets/initiate-upload

POST /v1/assets/initiate-upload HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 110

{
  "name": "conference_highlights.mov",
  "category": "video",
  "content_type": "video/quicktime",
  "size_bytes": 52428800
}

{
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "upload_id": "text",
  "s3_key": "text"
}

Get Pre-signed URL for Upload Part

post

Generates a pre-signed URL for uploading a specific part of a multipart upload. This endpoint will be called multiple times, once for each part of the file. Parts must be numbered sequentially starting from 1, and each part (except the last) must be at least 5MB in size (S3 requirement).

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Body

Payload to get a pre-signed URL for uploading a specific part of a multipart upload.

s3_keystringOptional

The S3 key for this asset.

asset_idstring · uuidRequired

The asset ID from the initiate upload response.

upload_idstringRequired

The multipart upload ID from the initiate upload response.

part_numberinteger · min: 1 · max: 10000Required

The part number for this upload part (1-10000).

Responses

200

Pre-signed URL generated successfully for the specified part.

application/json

Response containing the pre-signed URL for uploading a specific part.

upload_urlstring · urlRequired

The pre-signed S3 URL to PUT this specific part to.

part_numberintegerRequired

The part number this URL is for.

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

Multipart upload session not found.

application/json

post

/assets/sign-part

POST /v1/assets/sign-part HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "s3_key": "text",
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "upload_id": "text",
  "part_number": 1
}

{
  "upload_url": "text",
  "part_number": 1
}

Finalize Multipart Upload and Create Asset Record

post

Completes a multipart upload by combining all uploaded parts and creates the Asset metadata record in the Core API. The client must provide all part numbers and their corresponding ETags from the S3 upload responses. The Core API will complete the multipart upload in S3 and verify the final object before creating the database record.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Body

Payload to finalize a multipart asset upload and create the asset metadata record in DB.

asset_idstring · uuidRequired

The unique ID received from the 'initiate-upload' step.

upload_idstringRequired

The multipart upload ID from the 'initiate-upload' step.

namestringRequired

The original filename (must be consistent with initiate request).

categorystringRequired

The asset category (must be consistent with initiate request).

content_typestringRequired

Final confirmed MIME type of the asset.

size_bytesinteger · int64Required

Final confirmed size of the asset in bytes.

Responses

201

Multipart upload completed successfully and Asset record created in DB.

application/json

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

Multipart upload session not found.

application/json

409

Conflict with the current state of the resource.

application/json

post

/assets

POST /v1/assets HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "upload_id": "text",
  "name": "text",
  "category": "text",
  "content_type": "text",
  "size_bytes": 1,
  "parts": [
    {
      "part_number": 1,
      "etag": "text"
    }
  ]
}

{
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "org_123abc",
  "created_by": "user_789def",
  "name": "product_promo.mp4",
  "category": "video",
  "content_type": "video/mp4",
  "size_bytes": 10485760,
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

List Assets

get

Retrieves a list of Asset metadata. By default returns only organization-owned assets. Use source='template' to retrieve template assets instead. Supports pagination and filtering by category and name.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Query parameters

sourcestring · enumOptional

Filter items by ownership source. Use 'org' for items owned by the user's organization, 'template' for items from the template organization. Defaults to 'org'.

Default: orgPossible values:

categorystringOptional

Filter assets by category.

namestringOptional

Filter assets by name (e.g., for partial match - specific behavior TBD by implementation).

limitinteger · min: 1 · max: 100Optional

Number of items to return per page.

Default: 20

offsetintegerOptional

Number of items to skip for pagination.

Default: 0

Responses

200

A paginated list of Asset metadata.

application/json

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

get

/assets

GET /v1/assets HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "asset_id": "123e4567-e89b-12d3-a456-426614174000",
      "organization_id": "org_123abc",
      "created_by": "user_789def",
      "name": "product_promo.mp4",
      "category": "video",
      "content_type": "video/mp4",
      "size_bytes": 10485760,
      "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
      "created_at": "2026-05-21T07:39:52.864Z",
      "updated_at": "2026-05-21T07:39:52.864Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total_items": 150
  }
}

Retrieve Asset Metadata and Download URL

get

Retrieves metadata for a specific Asset, including a pre-signed URL for downloading the content. The user can access an asset if it belongs to their organization or to the shared template organization.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

asset_idstring · uuidRequired

The unique identifier (UUID) of the Asset.

Responses

200

Successfully retrieved Asset metadata, including a download URL.

application/json

Represents a digital asset managed by the Core API.

asset_idstring · uuidRead-onlyRequired

Unique identifier for the Asset, generated during upload initiation.

Example: 123e4567-e89b-12d3-a456-426614174000

organization_idstringRead-onlyRequired

ID of the Organisation (from external IdP) that owns this Asset. Server-set.

Example: org_123abc

created_bystringRead-onlyRequired

User ID of the creator (from external IdP). Server-set.

Example: user_789def

namestringRequired

The original file name of the Asset. NOT NULL.

Example: product_promo.mp4

categorystringRequired

Primary category of the Asset (e.g., 'video', 'image', 'weight'). NOT NULL. List of values managed in code.

Example: video

content_typestringRequired

The MIME type of the asset. NOT NULL.

Example: video/mp4

size_bytesinteger · int64Required

The size of the asset in bytes. NOT NULL.

Example: 10485760

etagstringRequired

The ETag of the S3 object, used for integrity checking. NOT NULL.

Example: "d41d8cd98f00b204e9800998ecf8427e"

created_atstring · date-timeRead-onlyRequired

Timestamp of when this Asset record was created (finalized). Server-generated. Defaults to CURRENT_TIMESTAMP.

updated_atstring · date-timeRead-onlyRequired

Timestamp of the last update to this Asset record. Server-generated. Auto-updates on modification.

asset_urlstring · uriRead-onlyOptional

A temporary, pre-signed URL to download the asset's content. This URL will expire.

Example: https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=...

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

get

/assets/{asset_id}/download

GET /v1/assets/{asset_id}/download HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "org_123abc",
  "created_by": "user_789def",
  "name": "product_promo.mp4",
  "category": "video",
  "content_type": "video/mp4",
  "size_bytes": 10485760,
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z",
  "asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}

Retrieve Asset Metadata

get

Retrieves metadata for a specific Asset. Does not include a download URL. The user can access an asset if it belongs to their organization or to the shared template organization.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

asset_idstring · uuidRequired

The unique identifier (UUID) of the Asset.

Responses

200

Successfully retrieved Asset metadata.

application/json

Represents a digital asset managed by the Core API.

asset_idstring · uuidRead-onlyRequired

Unique identifier for the Asset, generated during upload initiation.

Example: 123e4567-e89b-12d3-a456-426614174000

organization_idstringRead-onlyRequired

ID of the Organisation (from external IdP) that owns this Asset. Server-set.

Example: org_123abc

created_bystringRead-onlyRequired

User ID of the creator (from external IdP). Server-set.

Example: user_789def

namestringRequired

The original file name of the Asset. NOT NULL.

Example: product_promo.mp4

categorystringRequired

Primary category of the Asset (e.g., 'video', 'image', 'weight'). NOT NULL. List of values managed in code.

Example: video

content_typestringRequired

The MIME type of the asset. NOT NULL.

Example: video/mp4

size_bytesinteger · int64Required

The size of the asset in bytes. NOT NULL.

Example: 10485760

etagstringRequired

The ETag of the S3 object, used for integrity checking. NOT NULL.

Example: "d41d8cd98f00b204e9800998ecf8427e"

created_atstring · date-timeRead-onlyRequired

Timestamp of when this Asset record was created (finalized). Server-generated. Defaults to CURRENT_TIMESTAMP.

updated_atstring · date-timeRead-onlyRequired

Timestamp of the last update to this Asset record. Server-generated. Auto-updates on modification.

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

get

/assets/{asset_id}

GET /v1/assets/{asset_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "org_123abc",
  "created_by": "user_789def",
  "name": "product_promo.mp4",
  "category": "video",
  "content_type": "video/mp4",
  "size_bytes": 10485760,
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

Delete an Asset

delete

Permanently deletes an Asset's metadata from the DB and its corresponding object from S3 (hard delete). This operation is restricted to assets owned by the user's organization and cannot be used on shared template assets.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Path parameters

asset_idstring · uuidRequired

The unique identifier (UUID) of the Asset.

Responses

204

Operation successful, no content to return.

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

The requested resource was not found.

application/json

delete

/assets/{asset_id}

DELETE /v1/assets/{asset_id} HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Accept: */*

No content

The idle video generator endpoint still references the deprecated ojin/oris-1.0 model name. The underlying service uses the current Oris Portrait model. This endpoint path will be updated in a future release.

Generate idle video from image asset

post

Triggers background generation of an idle video from a source image asset using the ojin/oris-1.0 idle video generator.

The job runs asynchronously and returns a job_id for status tracking.

On completion, the generated video is saved as a new Asset in the organization. The result.asset_id field in the job object will contain the new asset ID.

Authorizations

X-API-KeystringRequired

API key for authenticated access to the Ojin REST API.

Body

Request payload to trigger idle video generation.

source_asset_idstring · uuidRequired

The ID of the source image asset to use for generating the idle video.

Example: 123e4567-e89b-12d3-a456-426614174000

reference_templatestring · enumOptional

The reference motion template to use (e.g., 'v1', 'v2', 'v3').

Example: v1Possible values:

Responses

202

Job accepted and queued for processing.

application/json

400

Invalid request payload or parameters.

application/json

401

Authentication token is missing, invalid, or expired.

application/json

403

Authenticated principal does not have permission.

application/json

404

Source asset not found.

application/json

post

/assets/generate/ojin/oris-1.0-idle-video-generator

POST /v1/assets/generate/ojin/oris-1.0-idle-video-generator HTTP/1.1
Host: api.ojin.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "source_asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "reference_template": "v1"
}

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000"
}

These unauthenticated endpoints are intended for browser clients such as the Ojin widget.

Retrieve a Model Configuration (Public)

get

Retrieves a specific Model Configuration by ID. This is the public variant of GET /model-configs/{model_config_id}, designed for use by the Ojin widget embedded on third-party domains. Uses permissive CORS and requires no authentication. Resources are accessed by their UUID.

Internal fields (organization_id, created_by) are stripped from the response.

Path parameters

model_config_idstring · uuidRequired

The unique identifier (UUID) of the Model Configuration.

Responses

200

Model Configuration details (without internal fields).

application/json

Public variant of ModelConfig for widget embedding. Strips internal fields (organization_id, created_by) that are not needed by the widget.

model_config_idstring · uuidRead-onlyRequired

Server-generated unique ID.

model_idstringRead-onlyRequired

ID of the parent Model, derived from the Model Variant.

model_variant_idstringRequired

ID of the ModelVariant being configured.

titlestringRequired

Title for the configuration.

created_atstring · date-timeRead-onlyRequired

Timestamp of creation.

updated_atstring · date-timeRead-onlyRequired

Timestamp of last update.

404

The requested resource was not found.

application/json

get

/public/model-configs/{model_config_id}

GET /v1/public/model-configs/{model_config_id} HTTP/1.1
Host: api.ojin.ai
Accept: */*

{
  "model_config_id": "123e4567-e89b-12d3-a456-426614174000",
  "model_id": "text",
  "model_variant_id": "text",
  "title": "text",
  "model_configurations": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z"
}

Retrieve Asset Metadata with Download URL (Public)

get

Retrieves metadata for a specific Asset, including a pre-signed download URL. This is the public variant of GET /assets/{asset_id}, designed for use by the Ojin widget embedded on third-party domains. Uses permissive CORS and requires no authentication. Resources are accessed by their UUID.

Internal fields (organization_id, created_by) are stripped from the response.

Path parameters

asset_idstring · uuidRequired

The unique identifier (UUID) of the Asset.

Responses

200

Successfully retrieved Asset metadata with download URL (without internal fields).

application/json

Public variant of Asset for widget embedding. Strips internal fields (organization_id, created_by) and includes a pre-signed download URL.

asset_idstring · uuidRead-onlyRequired

Unique identifier for the Asset.

Example: 123e4567-e89b-12d3-a456-426614174000

namestringRequired

The original file name of the Asset.

Example: product_promo.mp4

categorystringRequired

Primary category of the Asset (e.g., 'video', 'image', 'weight').

Example: video

content_typestringRequired

The MIME type of the asset.

Example: video/mp4

size_bytesinteger · int64Required

The size of the asset in bytes.

Example: 10485760

etagstringRequired

The ETag of the S3 object.

Example: "d41d8cd98f00b204e9800998ecf8427e"

created_atstring · date-timeRead-onlyRequired

Timestamp of creation.

updated_atstring · date-timeRead-onlyRequired

Timestamp of last update.

asset_urlstring · uriRead-onlyRequired

A temporary, pre-signed URL to download the asset's content. This URL will expire.

Example: https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=...

404

The requested resource was not found.

application/json

get

/public/assets/{asset_id}

GET /v1/public/assets/{asset_id} HTTP/1.1
Host: api.ojin.ai
Accept: */*

{
  "asset_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "product_promo.mp4",
  "category": "video",
  "content_type": "video/mp4",
  "size_bytes": 10485760,
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "created_at": "2026-05-21T07:39:52.864Z",
  "updated_at": "2026-05-21T07:39:52.864Z",
  "asset_url": "https://s3.amazonaws.com/ojin-assets/asset.mp4?X-Amz-Algorithm=..."
}

Schemas

PreviousGet your API key NextSupport

Last updated 19 days ago

Was this helpful?

Authentication

Model Configurations

List Model Configurations

Create a new Model Configuration

Retrieve a specific Model Configuration

Update an existing Model Configuration

Delete a Model Configuration

Model Variants

List all Model Variants

Retrieve a specific Model Variant

Assets

Initiate a Multipart Asset Upload

Get Pre-signed URL for Upload Part

Finalize Multipart Upload and Create Asset Record

List Assets

Retrieve Asset Metadata and Download URL

Retrieve Asset Metadata

Delete an Asset

Generate idle video from image asset

Public Widget Endpoints

Retrieve a Model Configuration (Public)

Retrieve Asset Metadata with Download URL (Public)

Schemas