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

A person must create the Jellypod account and complete Studio onboarding before connecting an agent. For HTTP or MCP bearer authentication, an administrator or member with permission to manage API keys creates a key in Developers and supplies it to the client. HTTP API access comes with every paid plan and the trial, and the MCP connector works on every plan. MCP clients that support OAuth can connect through the user's sign-in and approval instead; see MCP setup. Agents cannot create accounts or API keys through HTTP or MCP. Keep each returned content ID with its kind.

Choose an outputCopy Anchor Link

HTTP and MCP coverageCopy Anchor Link

For production editing, billing, and team management, use Studio or the API where an endpoint is documented.

Find IDsCopy Anchor Link

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 scriptCopy Anchor Link

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

• Prompt mode always writes new narration from the prompt and sources, even when that material is a finished script. To preserve narration, use script for videos and shorts, or POST /episodes/import over HTTP or generate_episode with script for episodes.
• 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 SourcesCopy Anchor Link

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 actionsCopy Anchor Link

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. Choose the next action from the evidence:

Follow recovery.idempotency_key when present. A polling timeout or lost response is not evidence of a pre-execution rejection.

Follow progressCopy Anchor Link

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.

MCP cannot retry failed generation in place. For a failed video, short, or voiceover, first use Studio or the HTTP retry endpoint for the existing item. A render-only retry costs no credits; other retries charge only for what they still generate. See retry and credits.

If the creator chooses to start over through MCP, disclose that creating new content is a new credit-bearing action and use a new idempotency key.

Read resultsCopy Anchor Link

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.