> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a new source upload (video or image) > Returns a `sourceId` and a pre-signed S3 URL. PUT the file bytes to `uploadUrl`, then reference `sourceId` from clips, layouts (b-roll media), overlays, or backgrounds. Use `kind: "image"` for images (no `duration`); Tella hosts the bytes for rendering, so you never deal with raw image URLs. ## OpenAPI ````yaml /openapi.json post /v1/sources openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per organization. Rate limit information is returned in response headers: - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when the window resets title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: Webhook endpoint management name: Webhooks paths: /v1/sources: post: tags: - Sources summary: Create a new source upload (video or image) description: >- Returns a `sourceId` and a pre-signed S3 URL. PUT the file bytes to `uploadUrl`, then reference `sourceId` from clips, layouts (b-roll media), overlays, or backgrounds. Use `kind: "image"` for images (no `duration`); Tella hosts the bytes for rendering, so you never deal with raw image URLs. operationId: createSource requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSourceRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateSourceResponse' description: OK '400': content: application/json: example: error: code: bad_request doc_url: https://tella.tv/docs/api-reference/errors#bad-request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. '401': content: application/json: example: error: code: unauthorized doc_url: https://tella.tv/docs/api-reference/errors#unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. '403': content: application/json: example: error: code: forbidden doc_url: https://tella.tv/docs/api-reference/errors#forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. '404': content: application/json: example: error: code: not_found doc_url: https://tella.tv/docs/api-reference/errors#not-found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. '422': content: application/json: example: error: code: unprocessable_entity doc_url: >- https://tella.tv/docs/api-reference/errors#unprocessable-entity message: The request was well-formed but contained semantic errors. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was well-formed but contained semantic errors. '429': content: application/json: example: error: code: rate_limit_exceeded doc_url: >- https://tella.tv/docs/api-reference/errors#rate-limit-exceeded message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. '500': content: application/json: example: error: code: internal_server_error doc_url: >- https://tella.tv/docs/api-reference/errors#internal-server-error message: An unexpected error occurred on the server. schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred on the server. security: - BearerAuth: [] components: schemas: CreateSourceRequest: additionalProperties: false description: >- Create a new source upload (video, audio, or image). Returns a pre-signed S3 URL to PUT the bytes to, plus a `sourceId` to reference from clips, layouts, overlays, backgrounds, and sound effects. properties: duration: description: >- Duration in seconds. Required for `video` and `audio`; ignored for `image`. exclusiveMinimum: true minimum: 0 type: number height: description: >- Height in pixels. Required for `video` and `image`; omit for `audio`. exclusiveMinimum: true maximum: 9007199254740991 type: integer kind: description: >- Source kind: `video` (default), `audio` (e.g. sound effects), or `image`. enum: - video - audio - image type: string width: description: Width in pixels. Required for `video` and `image`; omit for `audio`. exclusiveMinimum: true maximum: 9007199254740991 type: integer type: object CreateSourceResponse: additionalProperties: false properties: expiresAt: description: ISO-8601 timestamp at which `uploadUrl` stops accepting uploads. format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ type: string sourceId: description: ID of the new source. type: string uploadUrl: description: >- Pre-signed S3 URL. PUT the file bytes here (single PUT, max ~5GB). Upload the file as-is: any common container is accepted (MP4, MOV, WebM, MP3, WAV, M4A, …) — the `.mp4` in the URL path is just the storage key, not a container requirement. format: uri type: string required: - sourceId - uploadUrl - expiresAt type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: error: additionalProperties: false description: Error details properties: code: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - unprocessable_entity - rate_limit_exceeded - internal_server_error example: not_found type: string doc_url: description: Link to documentation for this error example: https://tella.tv/docs/api-reference/errors#not-found format: uri type: string message: description: Human-readable error message example: The requested resource was not found. type: string required: - code - message - doc_url type: object required: - error type: object securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ````