API documentation

Base URL: https://aigens.app. Create a key on the API page in the studio, then send it with every request in the Authorization header:

curl https://aigens.app/api/me \
  -H "Authorization: Bearer aig_YOUR_KEY"

• A key is shown only once, when it is created. If you lose it, revoke it and create a new one; each account can have up to 5 keys.
• A key can do everything the account can, including spending spirit stones. Never put a key in code that runs in a browser or in a public repository.
• Keys cannot be used to create or revoke keys, or for admin endpoints.

• Requests and responses are JSON (except file uploads, which use multipart forms).
• Errors return an HTTP status of 400 or above with { "error": "human-readable message", "code": "CODE" }. The message follows your Accept-Language header (Vietnamese by default). The code field is present when the error is one of the predefined kinds.
• Common statuses: 401 wrong or revoked key; 402 not enough spirit stones; 409 the action can't be done right now (a scene is rendering, a character has no image: CAST_NOT_READY); 422 the script doesn't match the format, with a list of issues per scene.
• Rate limits per account: reads (GET) 120 per minute, writes (POST, PATCH, DELETE) 20 per minute. Going over returns 429 with "code": "RATE_LIMITED" and a Retry-After header (seconds to wait). Sending a wrong key many times in a row blocks you for one minute.
• Three actions spend spirit stones: writing a script from an idea, sending scenes to render, and sending a trending video. Failed runs are refunded automatically.
• Rendering runs in the background. Polling the status every 5 to 15 seconds is enough.

When you call with an API key, content-generating actions have their own prices: rendering scenes and trending videos cost the website price times 150%, rounded up. First-time offers (your first video, your first trending run) are only available on the website; API calls don't get the discount and don't use it up either.

Current prices are always in GET /api/me, under pricing.api. The quote in GET /api/episodes/{id} already uses API prices when you call with a key. Every charge returns charged; the spirit stone ledger adds "(API)". A failed script draft is refunded right away.

The six steps below match the steps you click through on the website. A complete, runnable version is in the Python example at the top of this page.

Step 1. The system writes a script from your idea (free)

curl -X POST https://aigens.app/api/episodes/draft \
  -H "Authorization: Bearer $AIGENS_KEY" -H "Content-Type: application/json" \
  -d '{"idea": "The Tortoise and the Hare race a second time, with a surprise ending.", "sceneCount": 5, "voiceGender": "female"}'

# Returns: { "json": "<JSON prompt string>", "issues": [] }

A JSON prompt has the shape { title, style, characters: [{ key, name, description }], scenes: [{ prompt, voice }] }. You can edit it before creating the episode, or write the whole JSON yourself and skip this step. Whenever a character appears in a scene, that scene's prompt must mention the character's exact key.

Step 2. Create the episode (free)

curl -X POST https://aigens.app/api/episodes \
  -H "Authorization: Bearer $AIGENS_KEY" -H "Content-Type: application/json" \
  -d '{"json": "<JSON prompt string from step 1>", "aspect": "9:16", "voiceGender": "female", "captions": true}'

# Returns: { "id": "<episode id>" }

Step 3. Character images (free)

Read the episode to get its characters, request an image for each one, wait until the status becomes pending_review, then approve it. If you have your own image, upload it instead of generating one; uploaded images are approved right away.

curl https://aigens.app/api/episodes/$EPISODE -H "Authorization: Bearer $AIGENS_KEY"
# episode.cast: [{ "id": "...", "key": "character_tho", "status": "no_image" }, ...]

curl -X POST https://aigens.app/api/characters/episode/$CHARACTER/image   -H "Authorization: Bearer $AIGENS_KEY"
curl -X POST https://aigens.app/api/characters/episode/$CHARACTER/approve -H "Authorization: Bearer $AIGENS_KEY"

# Or use your own image:
curl -X POST https://aigens.app/api/characters/episode/$CHARACTER/upload \
  -H "Authorization: Bearer $AIGENS_KEY" -F "image=@hare.jpg;type=image/jpeg"

Step 4. Render (spends spirit stones)

curl -X POST https://aigens.app/api/episodes/$EPISODE/render \
  -H "Authorization: Bearer $AIGENS_KEY" -H "Content-Type: application/json" -d '{}'

# Returns: { "charged": 50, "scenes": 5, "balance": 450 }

The amount to be charged is in quote.total when you read the episode. To redo a few scenes, send {"sceneIds": ["<scene id>"]}.

Step 5. Wait for rendering and stitching

Read the episode again until episode.status is done. In automatic stitch mode, the system stitches as soon as the last scene is finished.

Step 6. Download the video

curl -L -o episode.mp4 https://aigens.app/api/episodes/$EPISODE/download -H "Authorization: Bearer $AIGENS_KEY"

Videos are kept for a limited time (see keepDays in /api/me). After that the video is deleted; the script and characters stay.

Send a character image together with a source video (a file, or a TikTok link). The system replaces the main character of the video with the character in the image and keeps the original audio.

curl -X POST https://aigens.app/api/trends \
  -H "Authorization: Bearer $AIGENS_KEY" \
  -F "character=@character.jpg;type=image/jpeg" \
  -F "video=@source.mp4;type=video/mp4"
# or replace the video line with:  -F "url=https://www.tiktok.com/@.../video/..."

# Returns: { "id": "<video id>", "cost": 30 }

curl https://aigens.app/api/trends -H "Authorization: Bearer $AIGENS_KEY"
# trends: [{ "id": "...", "status": "queued | processing | done | failed | expired", "error": null }], terms: { "cost": 30, "maxSeconds": 30 }

curl -L -o result.mp4 "https://aigens.app/api/trends/$VIDEO/video?download=1" -H "Authorization: Bearer $AIGENS_KEY"

You must state the file type in the form (type=image/jpeg, type=video/mp4); the server checks it. The price and the number of seconds used are in terms.

Rate limits apply only to calls with an API key and are counted per minute for each account (all keys of an account share them):

• Reads (GET): 120 per minute.
• Writes (POST, PATCH, DELETE): 20 per minute.
• Sending a wrong key 20 times within a minute from the same IP address blocks every key from that IP until the minute is over.
• Over the limit: HTTP 429, { "code": "RATE_LIMITED", "retryAfter": 37 }, with the headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

Content limits currently in effect (the same as on the website; the latest numbers are always in GET /api/me, under limits):

Every error returns JSON { "error": "human-readable message", "code": "CODE" }. Rely on code when it is present to handle errors in your script; the wording in error may change.

HTTP statuses

Values of code