# Upload and register source files Choose the shortest supported path to register hosted, small, or large files as reusable Lingopal jobs. URL: /guides/uploads/choose-upload-method Every file-based workflow starts with a reusable `job_id`. | Source | Use | | --------------------------------------- | -------------------------------------------------------------------- | | Publicly reachable URL | `POST /v2/jobs/register` | | Small local file | `POST /v2/jobs/upload-and-register` | | Large local file | `POST /v2/storage/uploads`, upload bytes, then register `source_url` | | Large file requiring multipart transfer | [Multipart uploads](/guides/uploads/multipart-upload) | ## Register an existing URL [#register-an-existing-url] ```bash export LINGOPAL_API_KEY="your-api-key" curl -X POST "https://api.lingopal.ai/v2/jobs/register" \ -H "X-API-Key: $LINGOPAL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "source_url": "https://example.com/source-file.mp4", "name": "sample-job", "media_type": "video" } ] }' ``` ## POST /v2/jobs/register ```json { "openapi": "3.1.0", "info": { "title": "Register jobs for later use", "description": "Lingopal v2 public API for text translation, storage uploads, registered jobs, job workflows, and job outputs.", "version": "v2" }, "servers": [ { "url": "https://vod-api.lingopal-dev.com" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/v2/jobs/register": { "post": { "tags": [ "Job Registration" ], "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" }, "example": { "message": "Job registration completed", "registered_count": 1, "error_count": 0, "results": [ { "name": "Product Demo", "source_url": "https://cdn.example.com/uploads/product-demo.mp4", "status": "registered", "job_id": "job_123", "media_type": "video" } ] } } } }, "401": { "description": "Missing or invalid authentication token." }, "422": { "description": "Request validation error." } }, "security": [ { "APIKeyHeader": [] } ] } } }, "tags": [ { "name": "Job Registration", "description": "Upload or register source files as reusable jobs." } ], "components": { "schemas": { "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" }, "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", "examples": [ { "error_count": 0, "message": "Job registration completed", "registered_count": 1, "results": [ { "job_id": "job_123", "media_type": "video", "name": "Product Demo", "source_url": "https://cdn.example.com/uploads/product-demo.mp4", "status": "registered" } ] } ] }, "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" }, "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" } }, "securitySchemes": { "APIKeyHeader": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } } } ``` Use the [API Reference entry for registerJobs](/reference/job-registration/registerJobs) for complete request rules and validation behavior. Send one to 100 items. Each item requires `source_url`; `name` and `media_type` are optional. Inspect every result because a batch can contain both successes and failures. ## Upload a small file [#upload-a-small-file] ```bash export LINGOPAL_API_KEY="your-api-key" curl -X POST "https://api.lingopal.ai/v2/jobs/upload-and-register" \ -H "X-API-Key: $LINGOPAL_API_KEY" \ -F "name=sample-video" \ -F "file=@/path/to/file.mp4" ``` ## POST /v2/jobs/upload-and-register ```json { "openapi": "3.1.0", "info": { "title": "Upload and register a small file", "description": "Lingopal v2 public API for text translation, storage uploads, registered jobs, job workflows, and job outputs.", "version": "v2" }, "servers": [ { "url": "https://vod-api.lingopal-dev.com" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/v2/jobs/upload-and-register": { "post": { "tags": [ "Job Registration" ], "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" }, "example": { "message": "Job registration completed", "registered_count": 1, "error_count": 0, "results": [ { "name": "Product Demo", "source_url": "https://cdn.example.com/uploads/product-demo.mp4", "status": "registered", "job_id": "job_123", "media_type": "video" } ] } } } }, "401": { "description": "Missing or invalid authentication token." }, "413": { "description": "File exceeds the direct upload limit." }, "422": { "description": "Request validation error." } }, "security": [ { "APIKeyHeader": [] } ] } } }, "tags": [ { "name": "Job Registration", "description": "Upload or register source files as reusable jobs." } ], "components": { "schemas": { "Body_uploadAndRegisterJob": { "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "title": "File", "description": "Small source file to upload and register.", "examples": [ "product-demo.mp4" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional display name for the registered job." }, "media_type": { "anyOf": [ { "type": "string", "enum": [ "video", "audio", "document" ] }, { "type": "null" } ], "title": "Media Type", "description": "Optional source type hint. If omitted, Lingopal infers it from the file." } }, "type": "object", "required": [ "file" ], "title": "Body_uploadAndRegisterJob" }, "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", "examples": [ { "error_count": 0, "message": "Job registration completed", "registered_count": 1, "results": [ { "job_id": "job_123", "media_type": "video", "name": "Product Demo", "source_url": "https://cdn.example.com/uploads/product-demo.mp4", "status": "registered" } ] } ] }, "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" } }, "securitySchemes": { "APIKeyHeader": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } } } ``` Use the [API Reference entry for uploadAndRegisterJob](/reference/job-registration/uploadAndRegisterJob) for complete request and response details. Send the file as `multipart/form-data`. If the API returns `413`, switch to storage upload. ## Upload a large file [#upload-a-large-file] Create a storage upload from the same workspace using `createStorageUpload`: ```bash export LINGOPAL_API_KEY="your-api-key" curl -X POST "https://api.lingopal.ai/v2/storage/uploads" \ -H "X-API-Key: $LINGOPAL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "file_ext": "mp4", "file_size": 2147483648 }' ``` ## POST /v2/storage/uploads ```json { "openapi": "3.1.0", "info": { "title": "Create a presigned storage upload", "description": "Lingopal v2 public API for text translation, storage uploads, registered jobs, job workflows, and job outputs.", "version": "v2" }, "servers": [ { "url": "https://vod-api.lingopal-dev.com" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/v2/storage/uploads": { "post": { "tags": [ "Storage" ], "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" }, "example": { "source_url": "https://cdn.example.com/presigned_upload/user_123/source.mp4", "file_path": "presigned_upload/user_123/source.mp4", "upload_id": "2~example-upload-id", "upload_urls": [ { "part_number": 1, "upload_url": "https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/source.mp4?partNumber=1&X-Amz-Signature=..." } ], "method": "PUT", "headers": { "Content-Type": "video/mp4" } } } } }, "401": { "description": "Missing or invalid authentication token." }, "422": { "description": "Request validation error." } }, "security": [ { "APIKeyHeader": [] } ] } } }, "tags": [ { "name": "Storage", "description": "Create and complete presigned storage uploads for source files." } ], "components": { "schemas": { "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" }, "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", "examples": [ { "file_path": "presigned_upload/user_123/source.mp4", "headers": { "Content-Type": "video/mp4" }, "method": "PUT", "source_url": "https://cdn.example.com/presigned_upload/user_123/source.mp4", "upload_id": "2~example-upload-id", "upload_urls": [ { "part_number": 1, "upload_url": "https://example-bucket.s3.amazonaws.com/presigned_upload/user_123/source.mp4?partNumber=1&X-Amz-Signature=..." } ] } ] }, "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" } }, "securitySchemes": { "APIKeyHeader": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } } } ``` Use the [API Reference entry for createStorageUpload](/reference/storage/createStorageUpload) for exact request and response fields. 1. Send `file_ext`; omit `file_size` for a single presigned PUT. 2. PUT raw file bytes to the returned upload URL using the returned headers. 3. Register the returned `source_url` with `POST /v2/jobs/register`. Do not send `X-API-Key` to the presigned storage URL unless its returned headers explicitly require it.