# info.description
REST API to create, edit, render and manage videos on EchoWave programmatically — projects, media, text, subtitles, AI voice-over (TTS), translation, renders, and one-shot media tools.

# tags[].description
Add, update and remove segments within a project timeline.

# tags[].description
Import or upload media files (video, audio, image).

# tags[].description
AI voice presets, voice clones, and text-to-speech generation.

# tags[].description
Transcription and translation of audio tracks.

# tags[].description
One-shot media processing tools (trim, crop, compress, etc.).

# tags[].description
Search and browse stock photo resources.

# paths./api/v1/health.get.description
Returns the current health status of the API and its dependencies. No authentication required.

# paths./api/v1/account.get.description
Returns information about the authenticated account including plan, credits, and usage counts.

# paths./api/v1/projects.get.description
Returns a paginated list of the authenticated user's projects.

# paths./api/v1/projects.post.description
Creates a new video project with the specified settings.

# paths./api/v1/projects/{id}.get.description
Returns a project with its full segment timeline.

# paths./api/v1/projects/{id}.patch.description
Updates top-level project metadata such as title, size, frame rate, background colour, or duration.

# paths./api/v1/projects/{id}.delete.description
Permanently deletes a project and all its associated segments.

# paths./api/v1/projects/{id}/segments.post.description
Adds a new segment to the project timeline. The segment type determines which additional fields are accepted.

# paths./api/v1/projects/{id}/segments/{segmentId}.patch.description
Partially updates a segment within the project timeline.

# paths./api/v1/projects/{id}/segments/{segmentId}.delete.description
Removes a segment from the project timeline.

# paths./api/v1/media.post.description
Imports a media file from a remote URL into EchoWave storage.

# paths./api/v1/media.post.requestBody.content.application/json.schema.properties.url.description
Publicly accessible URL of the media file to import.

# paths./api/v1/media.post.requestBody.content.application/json.schema.properties.projectId.description
Optional project to associate the upload with.

# paths./api/v1/media/upload.post.description
Uploads a media file directly via multipart form data.

# paths./api/v1/media/upload.post.requestBody.content.multipart/form-data.schema.properties.projectId.description
Optional project to associate the upload with.

# paths./api/v1/voices.get.description
Returns all available AI voice presets and the authenticated user's custom voice clones.

# paths./api/v1/tts.post.description
Synthesises speech from text using the specified AI voice and returns a reference to the generated audio upload.

# paths./api/v1/tts.post.requestBody.content.application/json.schema.properties.projectId.description
Project to associate the generated audio with.

# paths./api/v1/tts.post.requestBody.content.application/json.schema.properties.instruct.description
Optional natural-language instruction for voice style (model-dependent).

# paths./api/v1/tts.post.requestBody.content.application/json.schema.properties.model.description
Optional override for the TTS model to use.

# paths./api/v1/voices/clones.post.description
Creates a custom voice clone from an uploaded audio sample.

# paths./api/v1/voices/clones.post.requestBody.content.application/json.schema.properties.name.description
Human-readable name for the cloned voice.

# paths./api/v1/voices/clones.post.requestBody.content.application/json.schema.properties.storagePath.description
Storage path of the sample audio file previously uploaded.

# paths./api/v1/voices/clones.post.requestBody.content.application/json.schema.properties.sampleScript.description
Optional transcript of the sample audio to improve clone quality.

# paths./api/v1/voices/clones.post.requestBody.content.application/json.schema.properties.language.description
BCP-47 language code of the sample (e.g. en-US). Auto-detected if omitted.

# paths./api/v1/voices/clones/{id}.delete.description
Permanently deletes a custom voice clone.

# paths./api/v1/subtitles/transcribe.post.description
Queues a transcription job for an uploaded audio or video file.

# paths./api/v1/subtitles/transcribe.post.responses.202.content.application/json.schema.properties.data.properties.jobId.description
Identifier for tracking the transcription job.

# paths./api/v1/subtitles/translate.post.description
Queues a translation job for existing subtitles on an upload.

# paths./api/v1/subtitles/translate.post.requestBody.content.application/json.schema.properties.uploadId.description
ID of the upload whose subtitles should be translated.

# paths./api/v1/subtitles/translate.post.requestBody.content.application/json.schema.properties.targetLanguage.description
BCP-47 language code for the translation target (e.g. fr, es, ja).

# paths./api/v1/subtitles/translate.post.responses.202.content.application/json.schema.properties.data.properties.jobId.description
Identifier for tracking the translation job.

# paths./api/v1/subtitles/translate.post.responses.202.content.application/json.schema.properties.data.properties.alreadyExists.description
True if a translation to this language already existed and was returned immediately.

# paths./api/v1/renders.get.description
Returns a paginated list of render jobs, optionally filtered by project.

# paths./api/v1/renders.post.description
Queues a new render job for the specified project.

# paths./api/v1/renders/{id}.get.description
Returns the current status and result of a render job.

# paths./api/v1/renders/{id}/download.post.description
Returns a short-lived signed download URL for a completed render.

# paths./api/v1/renders/{id}/download.post.responses.200.content.application/json.schema.properties.data.properties.downloadUrl.description
Short-lived signed URL to download the rendered video.

# paths./api/v1/stock/photos.get.description
Searches the stock photo library and returns matching results.

# paths./api/v1/tools/{tool}.post.description
Queues a one-shot media processing operation (trim, crop, compress, etc.) and returns a render job reference.

# paths./api/v1/tools/{tool}.post.requestBody.content.application/json.schema.properties.options.description
Tool-specific options. Keys and values vary per tool.

# components.parameters.LimitParam.description
Maximum number of items to return per page.

# components.securitySchemes.ApiKeyAuth.description
API key from EchoWave account settings (/app/settings).

# components.securitySchemes.BearerAuth.description
OAuth JWT access token, a Firebase ID token, or an API key as a bearer token.

# components.securitySchemes.OAuth2.flows.authorizationCode.scopes.api:write
Create, edit and render EchoWave resources.

# components.responses.Unauthorized.description
Authentication credentials are missing or invalid.

# components.responses.Unauthorized.content.application/json.example.error.message
Authentication credentials are missing or invalid.

# components.responses.Forbidden.description
The authenticated user does not have permission to perform this action.

# components.responses.Forbidden.content.application/json.example.error.message
You do not have permission to perform this action.

# components.responses.ValidationError.description
Request body or parameters failed validation.

# components.responses.InternalError.content.application/json.example.error.message
An unexpected error occurred. Please try again.

# components.responses.ServiceUnavailable.content.application/json.example.error.message
The service is temporarily unavailable. Please try again later.

# components.schemas.Error.properties.error.properties.details.description
Field-level validation errors (present on 422 responses).

# components.schemas.Health.description
Map of dependency/service names to their health status.

# components.schemas.SizeObject.properties.ratio.description
Aspect ratio preset or 'custom' for arbitrary dimensions.

# components.schemas.SizeObject.properties.custom.description
Custom dimensions — required when ratio is 'custom'.

# components.schemas.CreateProjectRequest.properties.backgroundColor.description
Background fill colour as a CSS colour string (e.g. '#000000').

# components.schemas.UpdateProjectRequest.properties.backgroundColor.description
Background fill colour as a CSS colour string.

# components.schemas.ProjectSummary.properties.thumbnailUrl.description
URL of the project thumbnail image, if available.

# components.schemas.Project.description
Full project object without segment timeline.

# components.schemas.SegmentPosition.properties.x.description
Horizontal position in pixels from the left edge.

# components.schemas.SegmentPosition.properties.y.description
Vertical position in pixels from the top edge.

# components.schemas.SubtitleSegmentEntry.properties.id.description
Unique identifier for this subtitle cue.

# components.schemas.CutObject.properties.start.description
Trim-in point in milliseconds within the source media.

# components.schemas.CutObject.properties.end.description
Trim-out point in milliseconds within the source media.

# components.schemas.Segment.properties.id.description
Unique segment identifier (assigned by the server on creation).

# components.schemas.Segment.properties.type.description
Segment type. Determines which additional fields are accepted.

# components.schemas.Segment.properties.startTime.description
Segment start time on the project timeline in milliseconds.

# components.schemas.Segment.properties.endTime.description
Segment end time on the project timeline in milliseconds.

# components.schemas.Segment.properties.track.description
Track (row) index for the segment on the timeline.

# components.schemas.Segment.properties.zIndex.description
Stacking order — higher values render on top.

# components.schemas.Segment.properties.opacity.description
Segment opacity (0 = fully transparent, 1 = fully opaque).

# components.schemas.Segment.properties.text.description
(text segments) The text content to display.

# components.schemas.Segment.properties.fontSize.description
(text/subtitles segments) Font size in pixels.

# components.schemas.Segment.properties.bold.description
(text segments) Whether the text is bold.

# components.schemas.Segment.properties.italic.description
(text segments) Whether the text is italic.

# components.schemas.Segment.properties.color.description
(text/subtitles/wave/progress_bar/shape segments) Primary colour as a CSS colour string.

# components.schemas.Segment.properties.strokeWidth.description
(text segments) Text stroke (outline) width in pixels.

# components.schemas.Segment.properties.shadowBlur.description
(text segments) Text drop-shadow blur radius in pixels.

# components.schemas.Segment.properties.fileId.description
(video/audio/image/subtitles segments) ID of the associated upload or media file.

# components.schemas.Segment.properties.cut.description
(video/audio segments) Trim-in/out within the source media.

# components.schemas.Segment.properties.volume.description
(video/audio segments) Volume level (1 = 100%).

# components.schemas.Segment.properties.muted.description
(video/audio segments) Whether the audio track is muted.

# components.schemas.Segment.properties.parentId.description
(subtitles segments) ID of the parent video or audio segment this subtitle track belongs to.

# components.schemas.Segment.properties.verticalAlign.description
(subtitles segments) Vertical alignment of subtitle text.

# components.schemas.Segment.properties.caption.description
(subtitles segments) Caption styling preset.

# components.schemas.Segment.properties.subtitles.description
(subtitles segments) Inline subtitle cue data.

# components.schemas.Segment.properties.wave.description
(wave segments) Waveform style identifier.

# components.schemas.Segment.properties.bars.description
(wave segments) Number of bars in the waveform visualisation.

# components.schemas.Segment.properties.corners.description
(wave segments) Corner radius of waveform bars in pixels.

# components.schemas.Segment.properties.barType.description
(progress_bar segments) Progress bar style identifier.

# components.schemas.Upload.properties.storagePath.description
Internal storage path of the uploaded file.

# components.schemas.Upload.properties.url.description
Public or signed URL to access the upload, once ready.

# components.schemas.Upload.properties.durationMs.description
Duration in milliseconds (video and audio uploads only).

# components.schemas.Upload.properties.width.description
Width in pixels (video and image uploads only).

# components.schemas.Upload.properties.height.description
Height in pixels (video and image uploads only).

# components.schemas.Upload.properties.projectId.description
Associated project ID, if provided at import/upload time.

# components.schemas.Voice.properties.kind.description
Whether this is a built-in preset or a user-created clone.

# components.schemas.Voice.properties.language.description
BCP-47 language code the voice is optimised for.

# components.schemas.Voice.properties.previewUrl.description
URL to a short audio preview of this voice.

# components.schemas.Voice.properties.model.description
Underlying TTS model used by this voice.

# components.schemas.TtsResult.properties.source.description
Storage path or source reference for the generated audio.

# components.schemas.TtsResult.properties.durationMs.description
Duration of the generated audio in milliseconds.

# components.schemas.TtsResult.properties.cost.description
Number of credits deducted for this generation.

# components.schemas.Render.properties.outputUrl.description
URL of the rendered video output (present when status is 'completed').

# components.schemas.Render.properties.thumbnailUrl.description
URL of the render thumbnail (present when status is 'completed').

# components.schemas.Render.properties.watermark.description
Whether the rendered video includes an EchoWave watermark.

# components.schemas.Render.properties.durationMs.description
Duration of the rendered video in milliseconds.

# components.schemas.Render.properties.errorMessage.description
Human-readable error description (present when status is 'failed').

# components.schemas.Render.properties.createdAt.description
ISO 8601 timestamp when the render was queued.

# components.schemas.Render.properties.completedAt.description
ISO 8601 timestamp when the render completed or failed.

# components.schemas.RenderQueued.properties.status.description
Initial status — always 'queued' immediately after submission.

# components.schemas.StockPhoto.properties.description.description
Optional alt text or description of the photo.