API Documentation

Programmatic access to Instant Description for Enterprise users

Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key from the API Settings page.

Authorization Header

Authorization: Bearer id_live_your_api_key_here

Rate Limits

API requests are limited to 10 requests per minute. Exceeding this limit will return a 429 status code.

POST /api/v1/generate

Generate video descriptions from a publicly accessible video URL.

Request Body

Parameter	Type	Required	Description
`videoUrl`	`string`	Yes	Publicly accessible URL to the video file
`profileId`	`string`	Yes	ID of the brand profile to use
`mode`	`"single" \| "batch"`	Yes	Generation mode
`platform`	`string`	No	Required for single mode. One of: youtube, instagram, tiktok, facebook, linkedin, twitter
`platforms`	`string[]`	No	Required for batch mode. Array of platform names

Example Request

curl -X POST https://instantdescription.com/api/v1/generate \
  -H "Authorization: Bearer id_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/video.mp4",
    "profileId": "uuid-here",
    "mode": "single",
    "platform": "youtube"
  }'

Response

{
  "id": "generation-uuid",
  "generated_copy": "Your generated description...",
  "platform_copies": null,
  "platforms_selected": ["youtube"],
  "tokens_used": 48,
  "transcript": "Transcribed audio text..."
}

Batch Mode Response

{
  "id": "generation-uuid",
  "generated_copy": null,
  "platform_copies": {
    "youtube": "YouTube description...",
    "instagram": "Instagram caption..."
  },
  "platforms_selected": ["youtube", "instagram"],
  "tokens_used": 72,
  "transcript": "Transcribed audio text..."
}

JavaScript Example

const response = await fetch("https://instantdescription.com/api/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer id_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    videoUrl: "https://example.com/video.mp4",
    profileId: "uuid-here",
    mode: "batch",
    platforms: ["youtube", "instagram", "tiktok"],
  }),
});

const data = await response.json();
console.log(data.platform_copies);

GET /api/v1/profiles

List all brand profiles associated with your account.

Example Request

curl https://instantdescription.com/api/v1/profiles \
  -H "Authorization: Bearer id_live_your_api_key"

Response

[
  {
    "id": "profile-uuid",
    "name": "My Brand",
    "brand_rules": {
      "brand_voice": "Professional and friendly",
      "hashtag_strategy": "#brand #content"
    },
    "created_at": "2026-01-15T10:00:00Z"
  }
]

GET /api/v1/tokens

Check your current token balance and subscription details.

Example Request

curl https://instantdescription.com/api/v1/tokens \
  -H "Authorization: Bearer id_live_your_api_key"

Response

{
  "tokens_remaining": 3500,
  "tokens_reset_at": "2026-04-01T00:00:00Z",
  "subscription_tier": "enterprise"
}

Token Costs

Mode	Tokens Per Generation
Single platform	48 tokens
Batch (multi-platform)	72 tokens

Error Codes

Status	Description
`400`	Invalid input — missing or malformed request fields
`401`	Invalid API key or missing Authorization header
`403`	Not on Enterprise plan or insufficient tokens
`500`	Generation failed — server error during processing

Error Response Format

{
  "error": "Description of what went wrong"
}