AI Rap Video API and MCP Reference

AI Rap Generators provides an authenticated REST API and a remote Streamable HTTP MCP server. Both can create an original 15-second duo rap video, check its task status, and read the account credit balance. The video API uses the same task tracking, 10-credit reservation, provider workflow, and failure refunds as the website generator.

Endpoint and authentication

The MCP endpoint is https://airapgenerators.com/api/mcp. The versioned REST endpoints are:

| Method | Endpoint | Purpose | | ------ | -------------------------- | ----------------------------------------- | | POST | /api/v1/videos | Start an original duo rap video | | GET | /api/v1/videos/{videoId} | Read status and the result URL when ready | | GET | /api/v1/credits | Read the account balance and video cost | | GET | /api/v1/stages | List the supported stage templates |

All tool calls and REST requests require an AI Rap Generators account API key in Authorization: Bearer YOUR_API_KEY. Create or revoke keys in Settings → API Keys. Keep the key private and out of source control and logs. MCP tool discovery does not require a key; calling tools does.

REST responses use the { "code", "message", "data" } envelope. A video create request returns HTTP 202 with a task ID. MCP returns the same task data in structuredContent.

Create a video

POST /api/v1/videos accepts JSON. Provide exactly two direct, publicly accessible HTTPS image URLs. The server accepts domain hostnames and rejects local names and IP-address URLs. It does not upload or host the images for you; the generation provider must be able to retrieve each URL.

curl -X POST https://airapgenerators.com/api/v1/videos \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "imageUrls": [
      "https://images.example/performer-left.jpg",
      "https://images.example/performer-right.jpg"
    ],
    "stage": "hype-duo",
    "userInput": "Two friends celebrating a road trip",
    "occasion": "friends"
  }'

| Field | Requirement | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | imageUrls | Required array of exactly two HTTPS image URLs. Use authorized images; adults shown must consent, and real minors or public figures are not allowed. | | stage | Optional stage ID from GET /api/v1/stages; defaults to hype-duo. | | userInput | Optional creative direction up to 500 characters. | | occasion | Optional supported value: birthday, roast, christmas, friends, couple, anniversary, business, or custom. The stage supplies a default when omitted. |

The response includes id, status, stage, costCredits, and statusUrl. Each original video costs 10 credits, reserved when the task is created. If the provider cannot start or complete a render, the existing task system returns the reserved credits.

This API currently creates original duo videos. It does not create solo videos or meme remakes. For private image uploads, use the website generator, which has an authenticated upload flow. Do not publish private photos merely to make them reachable by an API.

Poll status and retrieve the result

Poll GET /api/v1/videos/{videoId} no more often than once every three seconds. The endpoint only returns tasks created through this public API by the account whose API key is used.

curl https://airapgenerators.com/api/v1/videos/YOUR_VIDEO_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

The response includes status (processing, success, or failed), costCredits, and videoUrl after a successful render. A failed task has no result URL and its reserved credits are restored.

Credits and stages

Call GET /api/v1/credits before starting a render. It returns balance, creditsPerVideo, and canCreateVideo. A video requires 10 credits. The API does not include a separate free video allowance; the account must have enough credits. The current signup-credit setting does not grant new accounts enough credits for a video, so do not promise a free first render.

GET /api/v1/stages lists the supported stage IDs and titles, along with the fixed duration, aspect ratio, resolution, and credit cost. For example, hype-duo is the default stage.

The MCP server exposes matching video tools: create_rap_video, get_video_status, get_credits, and list_rap_stages. It also retains the four text tools for names and lyric drafts. See the MCP guide for the complete schemas and Claude, Cursor, and Codex setup instructions.

Errors and limits

| HTTP status | Meaning | | ----------- | ---------------------------------------------------------------------- | | 400 | Invalid JSON, unsupported field, invalid stage, or invalid image URL | | 401 | Missing or invalid API key | | 402 | Account balance is below the 10-credit video cost | | 404 | Video task was not found for this account | | 413 | Request body is too large | | 429 | Create or poll request is rate limited; follow Retry-After | | 502 | The provider could not start a render or status could not be refreshed | | 503 | Video generation or authentication is temporarily unavailable | | 500 | An unexpected server error occurred |

MCP tool errors are returned with isError: true and a readable message. Invalid arguments are rejected before credit reservation. For help, contact support@airapgenerators.com.