Agent guide

Use the current schemas as the source of truth:

• HTTP: https://api.jellypod.com/v1 with Authorization: Bearer YOUR_API_KEY
• OpenAPI: https://api.jellypod.com/openapi.json
• MCP: https://mcp.jellypod.com/mcp with OAuth or a bearer API key

Create API keys in Developers. Keep each returned content ID with its kind.

Choose an output

Find IDs

For MCP, use list_content for podcasts, episodes, videos, shorts, and existing Voiceovers. Use list_characters for saved characters, list_voices when creating a character, and list_video_styles before creating a video or short. get_content needs only a content ID because Jellypod resolves its kind.

Voice IDs create characters. Character IDs select narrators for prompt-based generation. A finished script resolves bracketed speaker labels to saved Characters.

For HTTP, use GET /videos/options, GET /shorts/options, or GET /voiceovers/options. Use GET /hosts for character IDs.

Generate from a prompt or script

generate_episode, generate_video, and generate_short accept either a prompt or a finished script.

• Episode prompt mode always writes a new script from the prompt and sources, even when that material is a finished script. To preserve narration, use POST /episodes/import over HTTP or generate_episode with script over MCP.
• Prompt mode accepts optional sources and the character fields declared by the tool.
• Script mode uses a [Character Name] line before each turn.
• Match each label to a saved Character, or supply speaker_characters as [{"label": "Narrator", "character_id": "..."}]. Explicit assignments override name matching and must use active Characters in the current library.
• Text imports remove clearly unspoken titles and production directions while preserving speech and delivery tags. Uncertain lines stay; a failed judgement keeps the text as written, so production notes may be narrated.
• Script mode does not accept the prompt cast fields or sources.
• Video and short generation always require a style_id from list_video_styles.

Episodes start as drafts. Set auto_publish: true only when the creator explicitly asks to publish after a successful render. Use set_episode_publication to publish, schedule, reschedule, or unpublish an existing episode.

Supply Sources

MCP prompt generation accepts accessible webpage or YouTube URLs and plain text already held by the client. Jellypod saves this material as ordinary sources, but MCP does not expose source IDs or a separate source lifecycle.

MCP does not accept file handles, local paths, bytes, base64, private URLs, or saved source IDs. If the client can read a file, it can pass extracted plain text. Use Studio or HTTP when the original file matters. HTTP creation remains broader and accepts saved source IDs. Voiceovers remain a Studio or HTTP workflow.

For the HTTP upload flow and supported files, see Videos, shorts, and Voiceovers.

Prevent duplicate actions

Generation and metadata write tools accept an optional idempotency_key. Without one, every call starts a new action. For HTTP, send the Idempotency-Key header. A key protects a request for 24 hours.

Save the key before the request. Reuse it only with identical input after a lost or uncertain response. Once work starts, use a new key for a different request or a deliberate new generation. A proven rejection before work starts releases its claim, so fix the input or account issue and retry with the same key. If claim cleanup fails, the error instead asks for a new key. Older stored rejections also require a new key until their 24-hour expiry.

Follow progress

HTTP generation endpoints return 202, a content item in data, and a Location header. Every MCP generation tool returns id, kind, studio_url, and progress. generate_episode also returns publication_state, always draft at creation. Video and short results also return the settings Jellypod applied.

For MCP, call get_content with the id. When progress.poll_after_seconds is greater than zero, wait that long and poll again. An output may still be preparing after generation completes. A polling timeout does not mean generation failed. Reads and output checks do not start paid work.

A failed generation stays failed in MCP. After disclosing the new Credit-bearing action, create new content with a new idempotency key. The HTTP API retains its broader retry operations.

Read results

Check MCP isError before reading a result. Tools return structured content and concise text. Errors include error.recovery.action; input errors also identify affected fields. Resolve check_account in Studio, correct fields for correct_input, and use list_characters for choose_characters. Follow recovery.idempotency_key when present. After a proven pre-execution rejection, reuse means the claim was released and the corrected request can reuse its key; new means use another key. For an accepted or uncertain operation, reuse the key only with identical input. For check_result, check the saved content before repeating a write.

If publication returns render_not_ready or generation_not_ready, poll get_content after recovery.poll_after_seconds. Publish only once the content is ready, using a new key if the refusal specifies idempotency_key: "new". A missing render instead requires completing production in Studio.

See MCP setup and the MCP tool reference.