canonical: https://jentic.com/apis/cielo24api/cielo24api

# cielo-24 API

Jentic publishes the only available OpenAPI specification for cielo-24 API, keeping it validated and agent-ready. cielo-24 provides automated and human-verified captioning, transcription, and video intelligence services that turn audio and video files into searchable, indexed text. The API exposes job-based workflows for submitting media, requesting transcripts in multiple formats, retrieving an element list of words and timecodes, and managing account sessions. It is built around an account/login token model with eight job-management endpoints covering submission, status, retrieval, and deletion.

## For AI agents

Submit audio and video files to cielo-24 for captioning and transcription, then retrieve transcripts, caption files, and word-level timecodes for downstream search or accessibility workflows.

## Scope

Does not handle video hosting, video editing, or live streaming - use for captioning and transcription of pre-recorded media only.

## Capabilities

- Authenticate an account session and obtain an API access token via `/account/login`
- Create a new captioning or transcription job and attach media via `/job/new` and `/job/add_media`
- Trigger a transcription run with specified fidelity and priority via `/job/perform_transcription`
- Retrieve transcript text in TXT, SRT, WebVTT, or other supported formats via `/job/get_transcript`
- Pull a word-level element list with start and end timecodes via `/job/get_elementlist` for video search indexing
- Inspect job status, fidelity, and turnaround estimates via `/job/info`
- Delete completed or obsolete jobs via `/job/delete` to manage workspace storage

## Use cases

### Accessible Video Captioning

Generate compliant closed captions for educational, corporate, and broadcast video libraries by submitting source media to cielo-24 and retrieving SRT or WebVTT files once the job completes. The `/job/new` and `/job/perform_transcription` endpoints handle high-fidelity captioning with human verification, and `/job/get_transcript` returns the formatted caption file ready for upload to a player or VOD platform.

Example prompt: Create a new cielo-24 job for an MP4 URL at high fidelity, poll `/job/info` until the job is complete, and download the SRT transcript via `/job/get_transcript.`

### Video Search Indexing with Word-Level Timecodes

Make video libraries searchable by extracting word-level transcripts with start and end timestamps from cielo-24, then indexing the elements in a search engine so viewers can jump to the exact second a phrase is spoken. The `/job/get_elementlist` endpoint returns each word with its time offset, making this the source of truth for time-aligned video search.

Example prompt: Retrieve the element list for a completed cielo-24 job and emit one record per word with start_time, end_time, and word text for indexing into Elasticsearch.

### Bulk Transcription Workflow Automation

Process large batches of media files through cielo-24 by automating job creation, media attachment, transcription kickoff, status polling, and transcript retrieval. The eight job endpoints cover the full lifecycle so an automation script can submit hundreds of files, monitor turnaround, and pull finished transcripts without manual touch.

Example prompt: Iterate over a list of 50 media URLs, call `/job/new` for each, attach the URL via `/job/add_media`, trigger `/job/perform_transcription`, then poll `/job/info` until all are complete.

### AI Agent Captioning via Jentic

An AI agent receives a request to caption a podcast or video, searches Jentic for the captioning operation, loads the cielo-24 schema, and executes the job lifecycle without ever touching the API token directly. Jentic securely stores the cielo-24 access credentials and returns a scoped session, and the agent gets a finished transcript URL or text payload back in a single workflow.

Example prompt: Use the Jentic search query 'transcribe a video file' to find the cielo-24 job submission operation, load its schema, and execute it with the source media URL and desired fidelity.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/account/login` | Authenticate and obtain an API access token |
| POST | `/job/new` | Create a new captioning or transcription job |
| POST | `/job/add_media` | Attach a media file or URL to an existing job |
| POST | `/job/perform_transcription` | Trigger transcription at the requested fidelity |
| GET | `/job/info` | Retrieve job status, fidelity, and turnaround details |
| GET | `/job/get_transcript` | Download transcript in the requested format |
| GET | `/job/get_elementlist` | Retrieve word-level element list with timecodes |
| POST | `/job/delete` | Delete a job from the cielo-24 workspace |

## Key resources

- **Account** — Login and session token management for cielo-24 API access
- **Job** — Lifecycle for captioning and transcription jobs: create, attach media, run, inspect, retrieve transcript, fetch element list, delete

## Why Jentic

- **Setup:** Wiring cielo-24 by hand means logging in at `/account/login`, threading the session token through the new-job, add-media, transcription, and retrieval sequence, and cleaning up with delete yourself. Through Jentic you install once, import the cielo-24 API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** cielo-24 identifies jobs through parameters rather than a resource id in the URL path, so scope the agent to the operations it needs, such as creating a job, adding media, and getting a transcript. You choose that set, so deleting a job is not included unless you add it.
- **Credential handling:** Your cielo-24 account credentials and session tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'transcribe a video' or 'get a transcript', and Jentic returns the matching cielo-24 job operations with their input schemas so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AssemblyAI** — AI-first speech-to-text API with speaker labels and summarisation
- **Deepgram** — Real-time and batch speech-to-text API with speaker diarisation
- **Vimeo** — Video hosting platform that benefits from external captions

## FAQ

### Why is there no official OpenAPI spec for cielo-24 API?

cielo24 does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call cielo-24 API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the cielo-24 API use?

The API uses an apiKey token obtained from `/account/login` that is then passed on subsequent job calls. Through Jentic the login credentials live in the encrypted vault and the agent only ever sees a scoped session token, never the raw account password.

### Can I get word-level timecodes from cielo-24?

Yes. Once a transcription job completes, call `/job/get_elementlist` to receive each word with its start and end timecode, which is the basis for time-aligned video search and clip extraction.

### What transcript formats can I download from cielo-24?

`/job/get_transcript` supports plain text, SRT, and WebVTT among other caption formats. The exact format is selected via the request parameters when retrieving the finished transcript.

### How do I submit a new captioning job through Jentic?

Search Jentic for 'transcribe a video file', load the cielo-24 job submission schema, and execute against `/job/new` followed by `/job/add_media` and `/job/perform_transcription.` The Python SDK pattern is await client.search, await client.load, await client.execute.

### How do I check whether a cielo-24 transcription job is finished?

Call `/job/info` with the job ID to read the current status, fidelity, and turnaround estimate. Poll this endpoint at a reasonable interval until the status indicates the transcript is ready to download.

### Can I limit what my agent is allowed to do with the cielo-24 API?

Yes. Because Jentic One is self-hosted, you decide which cielo-24 operations your agent may call and which stored credentials it can use. You can allow only the operations a task needs, such as creating a job via `/job/new`, attaching media via `/job/add_media`, and downloading a transcript via `/job/get_transcript`, while leaving out destructive calls like `/job/delete` unless you explicitly grant them. Since cielo-24 identifies jobs through request parameters rather than resource IDs in the URL path, scoping happens at the operation level under your own rules.