Agent guide

Use this guide when building an agent that creates media in Jellypod. HTTP and MCP use the same product services and organization permissions. You can use HTTP from code or call the equivalent tools through an MCP client.

Connect and discover

• HTTP: use https://api.jellypod.com/v1 with Authorization: Bearer YOUR_API_KEY.
• MCP: connect to https://mcp.jellypod.com/mcp with Streamable HTTP. Authenticate through OAuth, or use a bearer API key when your client supports headers. See MCP setup.
• Read the live OpenAPI schema for HTTP request fields and responses. For MCP, initialize the connection and call tools/list; use each tool's inputSchema and outputSchema.

Create API keys in Developers. Keep a key in your application's secret store. Use returned IDs from the active organization; names, file paths, and URLs do not substitute for resource IDs.

For text-only documentation, read this page at /llms.mdx/docs/api/agents. The /llms.txt index links the rest of the documentation; the /llms-full.txt endpoint provides the combined documentation.

Choose the product before generating

A Voiceover produces a video using the supplied visuals. A Short belongs to the Shorts collection; selecting portrait orientation on a Video does not turn it into a Short. Keep the returned product object with its id, and use that product's endpoints or tools for later operations.

Podcast Episodes use Podcast Templates for their video output. Create a standalone Video or Short when the user wants generated visuals. There is no new Magic Video generation operation for Episodes.

Discover settings and existing resources

Call GET /videos/options, /shorts/options, or /voiceovers/options before assembling a request. The MCP equivalents are get_video_options, get_short_options, and get_voiceover_options.

The result includes saved narrator, language, style, and duration defaults, plus supported durations and styles. Use those values instead of inventing IDs or copying settings from a different product. default_host_id can be null; use GET /hosts or list_hosts to select an existing narrator. If the user's preferred narrator is unclear, resolve that choice before generation.

Use the user's authorized scope to decide what to create. Generation and an explicit retry consume credits. Status checks and download lookups do not start new generation. See credits and API access for billing and access requirements.

Supply Sources

Videos and Shorts accept a prompt and optional source_ids for research. They can start while valid Sources are processing; the workflow waits before reading that material. Missing or failed Sources are rejected.

Voiceovers require document or image Sources with processed visuals. Request file uploads with prepare_visuals: true, and wait until the Source reports status: "completed" before generating. Preserve source_ids order for the presentation. A URL Source or a file processed only for text is not a substitute for a visually prepared document.

For a file-capable MCP client:

1. Call request_source_upload with the file name, MIME type, byte size, and prepare_visuals: true for Voiceover input.
2. Transfer the bytes to upload.url using its returned method and headers. Do not put base64 file data in tool arguments or send the Jellypod API key to the storage URL.
3. Call complete_source_upload with the returned source.id as source_id.
4. Poll get_source and retain its ID. Source states are distinct from product states; a Source failure is error, not failed.

If the client cannot transfer file bytes, direct the user to Assets, then New Asset. Supported documents and images uploaded there are prepared for Voiceover. Find the upload with list_sources, check it with get_source, and use the returned ID. Do not say that an attachment was uploaded until the transfer has succeeded.

The file upload walkthrough includes the HTTP equivalent, file constraints, and an executable example.

Create once, then track the result

Save a unique key before a creation request. For Videos, Shorts, and Voiceovers, HTTP requires Idempotency-Key; MCP requires idempotency_key. Use the same key and unchanged input when resending a request after a timeout.

For example, these are the params for an MCP tools/call request:

{
  "name": "generate_short",
  "arguments": {
    "prompt": "Explain why leaves change color in autumn, for a beginner.",
    "target_duration_seconds": 30,
    "idempotency_key": "YOUR_SAVED_UNIQUE_REQUEST_KEY"
  }
}

For HTTP, send the same creation fields without idempotency_key in the body to POST /shorts, and put the key in the Idempotency-Key header. The product guide includes examples for all three products.

HTTP creation returns 202 with the product in data; this acknowledges the request, not finished media. MCP returns a tool result: check isError first, then read structuredContent, or parse the JSON text content when needed. Save the product ID as soon as it is available.

Detail, status, download, and retry tools take video_id, short_id, or voiceover_id, matching the product. Retry also takes a new idempotency_key. MCP product lists return rows, hasMore, and nextCursor; send nextCursor as cursor to get the next page. HTTP lists use a data array and a Link header for the next page.

Poll status using poll_after_seconds and HTTP Retry-After guidance. Product states are idle, generating, completed, and failed. Show the returned phase as progress rather than assuming a fixed sequence. Use a bounded polling period and retain the ID when you stop; a polling deadline is not a failed job.

After completed, request the download. delivery.kind: "available" supplies a URL. preparing means the file needs more time, so check again. unavailable means there is no downloadable output; show the returned Studio link from the product/status response. Do not start a new generation to obtain a missing download. Use studio_url for narration or scene editing.

Distinguish resends from new attempts

• Resending the same command uses the same key and input. A recorded acceptance replays its original response, so fetch status for current progress.
• Reusing a key with changed input returns a conflict. Fix the input and use a new key for an intentionally different creation request.
• An unresolved claim can return 409 even if the first response was lost. Check the resource ID in the error and retain the command ID for support. Do not submit a new key while the original acceptance is uncertain.
• Retry a confirmed failed product only when another paid attempt is authorized. Use its retry tool or POST /{collection}/{id}/retry with a new key. This keeps the product ID and starts a new generation attempt.

For existing podcasts, POST /episodes/generate and generate_episode accept optional keys with the same replay behavior. This does not make every podcast write idempotent. Other tools, including script import and publishing, have their own schemas and behavior. Episodes are generated as drafts; publishing is a separate action that needs the user's authorization.