Create storage uploads and register jobs for later use.
openapi: 3.1.0
info:
title: Lingopal API v2 Jobs Upload API
description: Lingopal API for uploading media and documents, starting translation workflows, generating subtitles, translating text, and downloading generated artifacts.
version: v2
servers:
- url: https://vod-api.lingopal-dev.com
security:
- APIKeyHeader: []
tags:
- name: Upload
description: Create storage uploads and register jobs for later use.
paths:
/v2/jobs/upload-and-register:
post:
tags:
- Upload
summary: Upload and register a small file
description: Uploads a small file directly to Lingopal and registers it as media or a document. For files larger than the direct upload limit, use `/v2/storage/uploads` multipart upload. Provide target languages and translation context later through the appropriate `/v2/jobs/{job_id}` workflow endpoint.
operationId: uploadAndRegisterJob
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_uploadAndRegisterJob'
examples:
directVideoJobUpload:
summary: Upload and register a small video file
description: Send the file bytes to Lingopal and receive a reusable job_id. Provide target languages later through the appropriate `/v2/jobs/{job_id}` workflow endpoint.
value:
file: product-demo.mp4
name: Product Demo
media_type: video
required: true
responses:
'200':
description: Registration result for the uploaded file.
content:
application/json:
schema:
$ref: '#/components/schemas/JobRegistrationResponse'
'401':
description: Missing or invalid authentication token.
'413':
description: File exceeds the direct upload limit.
'422':
description: Request validation error.
security:
- APIKeyHeader: []
/v2/jobs/register:
post:
tags:
- Upload
summary: Register jobs for later use
description: Registers one or more uploaded or externally hosted file URLs as Lingopal media/document records. This endpoint records source metadata only; processing inputs such as target languages and translation context are supplied later through the appropriate `/v2/jobs/{job_id}` workflow endpoint. Per-item failures are returned in the `results` array with `status="error"`.
operationId: registerJobs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JobRegistrationRequest'
examples:
registerSingleFile:
summary: Register one uploaded source URL
description: Register a source_url from `/v2/storage/uploads` as a reusable Lingopal file. Use the returned job_id with `/v2/jobs/{job_id}/translations` or `/v2/jobs/{job_id}/subtitles` to start processing.
value:
items:
- source_url: https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/product-demo.mp4
name: Product Demo
media_type: video
registerMixedFileBatch:
summary: Register multiple uploaded sources
description: Register several already-uploaded sources in one request. Upload endpoints do not accept target languages or translation context; provide those to the appropriate `/v2/jobs/{job_id}` workflow endpoint.
value:
items:
- source_url: https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/product-demo.mp4
name: Product Demo
media_type: video
- source_url: https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/interview.mp3
name: Customer Interview
media_type: audio
- source_url: https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/brief.pdf
name: Launch Brief
media_type: document
required: true
responses:
'200':
description: Per-item registration results.
content:
application/json:
schema:
$ref: '#/components/schemas/JobRegistrationResponse'
'401':
description: Missing or invalid authentication token.
'422':
description: Request validation error.
security:
- APIKeyHeader: []
/v2/storage/uploads:
post:
tags:
- Upload
summary: Create a presigned storage upload
description: Returns one or more presigned S3 upload URLs for uploading a source file before registering it with `/v2/jobs/register`. Provide `file_size` to request a multipart upload.
operationId: createStorageUpload
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorageUploadRequest'
examples:
singlePartStorageUpload:
summary: Create a single-part upload URL
description: Request one presigned PUT URL for a client-managed source upload. Register the returned source_url later with `/v2/jobs/register`.
value:
file_ext: mp4
multipartStorageUpload:
summary: Create multipart upload URLs
description: Request presigned part URLs for a large source upload. Complete the multipart upload with `/v2/storage/uploads/complete`, then register the returned source_url with `/v2/jobs/register`.
value:
file_ext: mp4
file_size: 524288000
required: true
responses:
'200':
description: Presigned upload metadata and upload part URLs.
content:
application/json:
schema:
$ref: '#/components/schemas/StorageUploadResponse'
'401':
description: Missing or invalid authentication token.
'422':
description: Request validation error.
security:
- APIKeyHeader: []
/v2/storage/uploads/complete:
post:
tags:
- Upload
summary: Complete a multipart storage upload
description: Completes an S3 multipart upload created by `/v2/storage/uploads`. Only uploads owned by the authenticated user can be completed.
operationId: completeStorageUpload
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteStorageUploadRequest'
examples:
completeMultipartStorageUpload:
summary: Complete multipart source upload
description: Finalize a multipart upload after every part has been uploaded to S3. Then register the returned source_url with `/v2/jobs/register`.
value:
file_path: presigned_upload/user_123/source.mp4
upload_id: 2~example-upload-id
etags:
- part_number: 1
etag: '"9b2cf535f27731c974343645a3985328"'
- part_number: 2
etag: '"2a1fd1f7bc39b3868d2a8f6fb50f6a7d"'
required: true
responses:
'200':
description: Completed storage upload location.
content:
application/json:
schema:
$ref: '#/components/schemas/CompleteStorageUploadResponse'
'401':
description: Missing or invalid authentication token.
'403':
description: The authenticated user cannot access this resource.
'422':
description: Request validation error.
security:
- APIKeyHeader: []
components:
schemas:
CompleteStorageUploadResponse:
properties:
file_path:
type: string
title: File Path
description: Storage path for the completed storage upload.
examples:
- presigned_upload/user_123/source.mp4
source_url:
type: string
title: Source Url
description: Final URL of the completed uploaded file.
examples:
- https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/source.mp4
type: object
required:
- file_path
- source_url
title: CompleteStorageUploadResponse
Body_uploadAndRegisterJob:
properties:
file:
type: string
contentMediaType: application/octet-stream
title: File
description: Small source file to upload and register.
name:
anyOf:
- type: string
- type: 'null'
title: Name
media_type:
anyOf:
- type: string
enum:
- video
- audio
- document
- type: 'null'
title: Media Type
type: object
required:
- file
title: Body_uploadAndRegisterJob
JobRegistrationItem:
properties:
source_url:
type: string
title: Source Url
description: Uploaded or externally hosted file URL to register as media or a document.
examples:
- https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/source.mp4
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Optional display name for the registered media/document.
examples:
- Product demo
media_type:
anyOf:
- type: string
enum:
- video
- audio
- document
- type: 'null'
title: Media Type
description: Optional media type hint. If omitted, Lingopal infers it from the file.
examples:
- video
additionalProperties: false
type: object
required:
- source_url
title: JobRegistrationItem
StorageUploadResponse:
properties:
source_url:
type: string
title: Source Url
description: Final URL of the uploaded file after upload completion.
examples:
- https://example-bucket.s3.amazonaws.com/presigned_upload/user/file.mp4
file_path:
type: string
title: File Path
description: Storage path for the storage upload. Use this when completing multipart uploads.
examples:
- presigned_upload/user_123/source.mp4
upload_id:
anyOf:
- type: string
- type: 'null'
title: Upload Id
description: S3 multipart upload ID. Present only when the storage upload uses multipart upload.
examples:
- 2~example-upload-id
upload_urls:
items:
$ref: '#/components/schemas/UploadPart'
type: array
title: Upload Urls
description: Presigned upload URLs, one per upload part.
method:
type: string
const: PUT
title: Method
description: HTTP method clients must use for each presigned upload URL.
default: PUT
headers:
additionalProperties:
type: string
type: object
title: Headers
description: Additional headers clients should send with the upload request.
examples:
- {}
type: object
required:
- source_url
- file_path
title: StorageUploadResponse
StorageUploadRequest:
properties:
file_ext:
type: string
minLength: 1
title: File Ext
description: Source file extension, with or without a leading dot.
examples:
- mp4
- wav
- pdf
file_size:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
title: File Size
description: Source file size in bytes. Provide this value to request multipart presigned upload URLs; omit it for a single PUT upload URL.
examples:
- 104857600
type: object
required:
- file_ext
title: StorageUploadRequest
JobRegistrationRequest:
properties:
items:
items:
$ref: '#/components/schemas/JobRegistrationItem'
type: array
maxItems: 100
minItems: 1
title: Items
description: One or more uploaded files to register.
type: object
required:
- items
title: JobRegistrationRequest
CompleteStorageUploadRequest:
properties:
file_path:
type: string
title: File Path
description: Storage path returned by `/v2/storage/uploads` for the multipart upload.
examples:
- presigned_upload/user_123/source.mp4
upload_id:
type: string
title: Upload Id
description: Multipart upload ID returned by `/v2/storage/uploads`.
examples:
- 2~example-upload-id
etags:
items:
anyOf:
- $ref: '#/components/schemas/CompletedUploadPart'
- type: string
type: array
minItems: 1
title: Etags
description: ETags for uploaded parts, ordered by part number. String ETags are accepted for compatibility.
type: object
required:
- file_path
- upload_id
- etags
title: CompleteStorageUploadRequest
JobRegistrationResult:
properties:
name:
type: string
title: Name
description: Display name used for the registered item.
source_url:
type: string
title: Source Url
description: Source URL submitted for this item.
status:
type: string
enum:
- registered
- error
title: Status
description: Whether this item was registered or failed validation/registration.
job_id:
anyOf:
- type: string
- type: 'null'
title: Job Id
description: Reusable registered job ID when registration succeeds.
examples:
- job_123
media_type:
anyOf:
- type: string
enum:
- video
- audio
- document
- type: 'null'
title: Media Type
description: Detected or supplied media type for the registered item.
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Per-item error message when `status` is `error`.
type: object
required:
- name
- source_url
- status
title: JobRegistrationResult
CompletedUploadPart:
properties:
part_number:
type: integer
exclusiveMinimum: 0
title: Part Number
description: One-based part number returned by the storage upload response.
examples:
- 1
etag:
type: string
title: Etag
description: ETag returned by S3 after uploading this part.
examples:
- '"9b2cf535f27731c974343645a3985328"'
type: object
required:
- part_number
- etag
title: CompletedUploadPart
UploadPart:
properties:
part_number:
type: integer
title: Part Number
description: One-based multipart upload part number.
examples:
- 1
upload_url:
type: string
title: Upload Url
description: Presigned URL used to upload this part with the documented HTTP method.
examples:
- https://example-bucket.s3.amazonaws.com/presigned_upload/user/file.mp4?X-Amz-Signature=...
type: object
required:
- part_number
- upload_url
title: UploadPart
JobRegistrationResponse:
properties:
message:
type: string
title: Message
description: Human-readable summary of the batch registration result.
registered_count:
type: integer
title: Registered Count
description: Number of items successfully registered.
examples:
- 1
error_count:
type: integer
title: Error Count
description: Number of items that failed registration.
examples:
- 0
results:
items:
$ref: '#/components/schemas/JobRegistrationResult'
type: array
title: Results
description: Per-item registration results.
type: object
required:
- message
- registered_count
- error_count
- results
title: JobRegistrationResponse
securitySchemes:
APIKeyHeader:
in: header
name: X-API-Key
type: apiKey