Public guide for humans and agents

FoxStoria stories, with one page your agent can follow.

This page explains how to get a personal FoxStoria API key, discover valid story options, create a story job, poll for the result, and return the final public share link.

Get your API key Read the OpenAPI spec

Human setup Agent workflow API quickstart Machine-readable guide Prompt to paste

Premium required

Personal API keys are created from a premium FoxStoria account.

Generates a Robo-Story

Each request produces a finished, narrated Robo-Story with images, sound effects, and music.

Share URL on finish

Completed stories return a public FoxStoria link you can open or share immediately.

Start here

Human setup

The easiest workflow is: create your key once, hand it to your agent, and let the agent handle the rest. The key lives at foxstoria.com/api-keys.

1Sign in to a FoxStoria premium account.
2Open /api-keys and create a personal API key.
3Copy the key immediately. FoxStoria only shows the full key once.
4Give that key to your agent and keep your Robo-Story balance topped up.

The full API key is only shown once at creation time. If you lose it, regenerate it from the API key page and update your agent.

What an agent should do

Agent workflow

If you point an agent at this page, the agent should be able to do most of the work with minimal follow-up questions.

1Read the public OpenAPI document first.
2If the human has not given you an API key yet, guide them to /api-keys.
3Ask for the story idea if the about field is still missing.
4If you need valid genre, format, or narrator IDs, fetch the public discovery endpoints.
5Create the story job with x-api-key and the JSON body.
6Poll the story endpoint until the job reaches a terminal state.
7Return shareUrl when status is COMPLETED, or surface the error or status if not.

Recommended rule

If the human does not care about specific IDs, send only about and let FoxStoria use its defaults.

Safety rule

Keep prompts child-safe for ages 3–10. Unsafe prompts can end in a VIOLATED status instead of a finished story.

API

Quickstart

1. Read the spec

Canonical public contract: https://foxstoria.com/v1/agent/openapi.json

2. Smallest valid story request

The only required field is about. Keep it at or under 2,000 characters.

bash

curl -X POST https://foxstoria.com/v1/agent/stories \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "about": "A calm bedtime story about Luna the fox helping a shy firefly light the path home."
  }'

3. Poll until the story finishes

Treat PROCESSING as in progress. A completed job returns a shareUrl.

bash

curl https://foxstoria.com/v1/agent/stories/STORY_ID \
  -H "x-api-key: YOUR_API_KEY"

4. Discover valid IDs when you need them

These public endpoints let an agent discover current story formats, story genres, and narrators before creating the job.

bash

curl https://foxstoria.com/v1/story-formats
curl https://foxstoria.com/v1/story-genres
curl https://foxstoria.com/v1/gen-story-narrators

Authentication header: Use x-api-key with the personal API key value.
Defaults: If omitted, FoxStoria defaults to English, illustration image style, 1:1 images, automatic writing-style selection, and media generation enabled.
Safe values: For imageAspectRatio, use only 1:1 or 9:16.
Terminal states: COMPLETED, ERRORED, VIOLATED, REVIEW_DECLINED
Common errors: 401 invalid key, 402 out of Robo-Stories, 403 premium required, 400 invalid request body.

Machine-readable

Agent manifest

Agents that prefer structured guidance can parse the JSON manifest below. The same JSON is also embedded on this page in a script[type="application/json"] tag with the id foxstoria-agent-manifest.

json

{
  "name": "FoxStoria Agent Story Guide",
  "version": "1.0",
  "guideUrl": "https://foxstoria.com/for-agents/",
  "audience": [
    "humans",
    "agents"
  ],
  "setup": {
    "apiKeysPageUrl": "https://foxstoria.com/api-keys",
    "premiumRequired": true,
    "product": "Robo-Story",
    "creditsPerRequest": 1,
    "keyVisibility": "shown_once_on_creation"
  },
  "auth": {
    "type": "apiKey",
    "header": "x-api-key",
    "fallbackHeader": "Authorization: Bearer <API_KEY>"
  },
  "endpoints": {
    "openApi": "https://foxstoria.com/v1/agent/openapi.json",
    "createStory": {
      "method": "POST",
      "url": "https://foxstoria.com/v1/agent/stories"
    },
    "getStory": {
      "method": "GET",
      "urlTemplate": "https://foxstoria.com/v1/agent/stories/{storyId}"
    },
    "getPublicShare": {
      "method": "GET",
      "urlTemplate": "https://foxstoria.com/v1/public/story-shares/{shareToken}"
    },
    "discovery": {
      "storyFormats": "https://foxstoria.com/v1/story-formats",
      "storyGenres": "https://foxstoria.com/v1/story-genres",
      "narrators": "https://foxstoria.com/v1/gen-story-narrators"
    }
  },
  "request": {
    "required": [
      "about"
    ],
    "optional": [
      "lang",
      "storyGenreId",
      "storyFormatId",
      "narratorId",
      "storyStyle",
      "imageStyle",
      "imageAspectRatio",
      "generateImages",
      "generateNarration",
      "generateSfx",
      "generateBackgroundMusic",
      "characters"
    ],
    "constraints": {
      "aboutMaxLength": 2000,
      "imageAspectRatioAllowedValues": [
        "1:1",
        "9:16"
      ],
      "unsupportedStoryFormatId": "mini"
    }
  },
  "defaultsWhenOmitted": {
    "lang": "en",
    "imageStyle": "illustration",
    "imageAspectRatio": "1:1",
    "storyStyle": "FoxStoria chooses a writing style automatically",
    "generateImages": true,
    "generateNarration": true,
    "generateSfx": true,
    "generateBackgroundMusic": true
  },
  "safety": {
    "targetAudience": "children ages 3-10",
    "keepPromptChildSafe": true,
    "flaggedPromptStatus": "VIOLATED"
  },
  "workflow": [
    "Read the public OpenAPI document first.",
    "If the human has not given you an API key yet, guide them to /api-keys.",
    "Ask for the story idea if 'about' is still missing.",
    "If you need valid genre, format, or narrator IDs, fetch the public discovery endpoints.",
    "Create the story job with x-api-key and the JSON body.",
    "Poll the story endpoint until the job reaches a terminal state.",
    "Return the shareUrl when status is COMPLETED, or surface the error/status if not."
  ],
  "terminalStatuses": [
    "COMPLETED",
    "ERRORED",
    "VIOLATED",
    "REVIEW_DECLINED"
  ]
}

Copy and paste

Prompt to hand to your agent

If you want an external agent to do most of the work for you, send it this prompt:

Prompt

Read https://foxstoria.com/for-agents/ and follow it.
Help me get a FoxStoria API key at https://foxstoria.com/api-keys.
Once I share the key, create a child-safe FoxStoria story for this idea:
[PUT THE STORY IDEA HERE]

Use FoxStoria defaults unless I explicitly ask for a specific genre, format, narrator, or style.
If you need valid IDs, fetch the public discovery endpoints from the guide.
Poll until the story finishes and give me the final share URL.

Replace the bracketed story idea with your own request, or append details like desired genre, narrator, or format if you already know them.