{"_id":"@androettop/synthesia-sdk","_rev":"3-15021f7f9bf22a801c67c8c71c725d18","name":"@androettop/synthesia-sdk","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@androettop/synthesia-sdk","version":"1.0.0","keywords":["synthesia","api","sdk","typescript","video"],"author":"","license":"MIT","_id":"@androettop/synthesia-sdk@1.0.0","maintainers":[{"name":"androettop","email":"androettop@gmail.com"}],"dist":{"shasum":"6dea8e84b2688d59bb0c6578969ef44eb0a85ff9","tarball":"https://registry.npmjs.org/@androettop/synthesia-sdk/-/synthesia-sdk-1.0.0.tgz","fileCount":93,"integrity":"sha512-Jfx1ltya+Dy3Ntmonm/M7WLlrnYKY+Dt9/aASiN03Ds82AyrPMXC2WOuxQeowG2n1Kj0mo3vNv5yHlW62JxRPQ==","signatures":[{"sig":"MEYCIQDfOa3akg0blQYTHP6mi5HE4rOLvV+noqtwffP81n6mfwIhAPSYmNvVuIpMrKTWOiGs3ctGc74iL4vFTEV90kUCEayx","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":638965},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"586dfd1d7f02235719b1a3c436d4c0a51b087f59","scripts":{"dev":"ts-node src/index.ts","test":"jest","build":"tsc","test:watch":"jest --watch","prepublishOnly":"npm run build","test:integration":"jest --testPathPattern=integration.test.ts"},"_npmUser":{"name":"androettop","email":"androettop@gmail.com"},"_npmVersion":"10.9.3","description":"TypeScript SDK for Synthesia API","directories":{},"_nodeVersion":"22.18.0","dependencies":{"axios":"^1.5.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.1","ts-node":"^10.9.1","typescript":"^5.2.2","@types/jest":"^29.5.5","@types/node":"^20.6.3"},"_npmOperationalInternal":{"tmp":"tmp/synthesia-sdk_1.0.0_1756189639797_0.2754924939436676","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@androettop/synthesia-sdk","version":"1.1.0","keywords":["synthesia","api","sdk","typescript","video"],"author":"","license":"MIT","_id":"@androettop/synthesia-sdk@1.1.0","maintainers":[{"name":"androettop","email":"androettop@gmail.com"}],"dist":{"shasum":"a110ab77b0a02c9d3feea6444cdfe3f3e5fe4ae6","tarball":"https://registry.npmjs.org/@androettop/synthesia-sdk/-/synthesia-sdk-1.1.0.tgz","fileCount":94,"integrity":"sha512-gpqrximItDLZIl3aGn3AHiEBVZ88rd69kPTuFL5R8iiEuHuue7CrJz/BMF3Gpsa50pArzZCncAxlaHLfxKgmYA==","signatures":[{"sig":"MEQCIFFb9LBuQEgE2Ku2UJTOzw9aWBnE6Hnb5lt8p0Z0FmxPAiAKRYCaq+geON2LSN4QKIwg7knvuWacsOrXs5rs8tOmkA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":666236},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"346ac93aac2bd42c988a09e3b4dfcb27482da8fc","scripts":{"dev":"ts-node src/index.ts","test":"jest","build":"tsc","test:watch":"jest --watch","prepublishOnly":"npm run build","test:integration":"jest --testPathPattern=integration.test.ts"},"_npmUser":{"name":"androettop","email":"androettop@gmail.com"},"_npmVersion":"10.9.3","description":"TypeScript SDK for Synthesia API","directories":{},"_nodeVersion":"22.18.0","dependencies":{"axios":"^1.5.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.1","ts-node":"^10.9.1","typescript":"^5.2.2","@types/jest":"^29.5.5","@types/node":"^20.6.3"},"_npmOperationalInternal":{"tmp":"tmp/synthesia-sdk_1.1.0_1756195644420_0.8684078104455315","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@androettop/synthesia-sdk","version":"1.2.0","description":"TypeScript SDK for Synthesia API","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"jest","test:watch":"jest --watch","test:integration":"jest --testPathPattern=integration.test.ts","dev":"ts-node src/index.ts","prepublishOnly":"npm run build"},"keywords":["synthesia","api","sdk","typescript","video"],"author":"","license":"MIT","devDependencies":{"@types/jest":"^29.5.5","@types/node":"^20.6.3","jest":"^29.7.0","ts-jest":"^29.1.1","ts-node":"^10.9.1","typescript":"^5.2.2"},"dependencies":{"axios":"^1.5.0"},"_id":"@androettop/synthesia-sdk@1.2.0","gitHead":"6f8d508536126e49d31e1c708d002cab79d220de","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-OXqLBCur1YBzQlqNr5E4nI5FtFFnyIQgajhiIDO9SPT+vfdRJlOQ3MgLNPPY6pMaBpEN9gxng4I0At6TxJK63g==","shasum":"18e147cedd74da7dd867f5ab9f5d472e5d64188d","tarball":"https://registry.npmjs.org/@androettop/synthesia-sdk/-/synthesia-sdk-1.2.0.tgz","fileCount":94,"unpackedSize":667812,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCx5/RxdXqOR060oZsD9GRnMYJ9VS1m+x8RNItreqgFugIgWAWrv5zdK40jf6ot5kHnlV7iyQVOgLh5U/ySRd2EVco="}]},"_npmUser":{"name":"androettop","email":"androettop@gmail.com"},"directories":{},"maintainers":[{"name":"androettop","email":"androettop@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/synthesia-sdk_1.2.0_1756198569318_0.015401139029404876"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-26T06:27:19.701Z","modified":"2025-08-26T08:56:09.888Z","1.0.0":"2025-08-26T06:27:20.041Z","1.1.0":"2025-08-26T08:07:24.654Z","1.2.0":"2025-08-26T08:56:09.738Z"},"license":"MIT","keywords":["synthesia","api","sdk","typescript","video"],"description":"TypeScript SDK for Synthesia API","maintainers":[{"name":"androettop","email":"androettop@gmail.com"}],"readme":"# Synthesia TypeScript SDK\n\nA comprehensive TypeScript SDK for the Synthesia API that allows you to create AI-generated videos programmatically.\n\n## Features\n\n- 🎥 **Video Creation**: Create videos with custom scripts, avatars, and backgrounds\n- 📋 **Template Support**: Use Synthesia templates for quick video generation\n- 🔗 **Webhook Management**: Set up webhooks to receive video processing notifications\n- 📁 **Asset Upload**: Upload audio, image, and video assets\n- 🔒 **Type Safety**: Full TypeScript support with comprehensive type definitions\n- ✅ **Comprehensive Testing**: Complete test suite for all endpoints\n- 🚨 **Error Handling**: Robust error handling with custom error types\n- ⚡ **Rate Limit Handling**: Built-in rate limit information tracking\n\n## 📖 Documentation\n\nFor comprehensive documentation, guides, and examples, visit: **[https://androettop.github.io/synthesia-sdk](https://androettop.github.io/synthesia-sdk)**\n\n## Installation\n\n```bash\nnpm install @androettop/synthesia-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { Synthesia } from \"@androettop/synthesia-sdk\";\n\nconst synthesia = new Synthesia({\n  apiKey: \"your-api-key-here\",\n});\n\n// Create a simple video\nconst result = await synthesia.videos.createVideo({\n  input: [{\n    scriptText: \"Hello world! This is my first Synthesia video.\",\n    avatar: \"anna_costume1_cameraA\",\n    background: \"green_screen\"\n  }],\n  title: \"My First Video\",\n  visibility: \"private\",\n  aspectRatio: \"16:9\",\n  test: true, // Use test mode for development\n});\n\nif (result.error) {\n  console.error(\"Error:\", result.error.message);\n} else {\n  console.log(\"Video created:\", result.data.id);\n}\n```\n\n## API Reference\n\n### Configuration\n\n```typescript\nconst synthesia = new Synthesia({\n  apiKey: \"your-api-key\", // Required: Your Synthesia API key\n  baseURL: \"https://custom.api\", // Optional: Custom API base URL\n});\n```\n\n### Videos API\n\n#### Create Video\n\n```typescript\nconst result = await synthesia.videos.createVideo({\n  input: [{\n    scriptText: \"Your script text\",\n    avatar: \"anna_costume1_cameraA\",\n    background: \"green_screen\"\n  }],\n  title: \"Video Title\",\n  visibility: \"private\", // Required: 'public' | 'private'\n  aspectRatio: \"16:9\", // Required: aspect ratio\n  test: true, // Optional: test mode\n  callbackId: \"callback-id\", // Optional: for tracking\n});\n```\n\n#### List Videos\n\n```typescript\nconst result = await synthesia.videos.listVideos({\n  source: \"workspace\", // Optional: 'workspace' | 'my_videos' | 'shared_with_me'\n  limit: 10, // Optional: number of videos to return (max 100)\n  offset: 0, // Optional: pagination offset\n});\n```\n\n#### Get Video\n\n```typescript\nconst result = await synthesia.videos.getVideo(\"video-id\");\n```\n\n#### Update Video\n\n```typescript\nconst result = await synthesia.videos.updateVideo(\"video-id\", {\n  title: \"New Title\",\n  visibility: \"public\",\n});\n```\n\n#### Delete Video\n\n```typescript\nconst result = await synthesia.videos.deleteVideo(\"video-id\");\n```\n\n#### Create Video from Template\n\n```typescript\nconst result = await synthesia.videos.createVideoFromTemplate(\n  \"template-id\",\n  {\n    // Template variables\n    name: \"John Doe\",\n    company: \"Acme Corp\",\n  },\n  {\n    title: \"Personalized Video\",\n    test: true,\n  }\n);\n```\n\n### Templates API\n\n#### List Templates\n\n```typescript\nconst result = await synthesia.templates.listTemplates({\n  source: \"synthesia\", // Optional: 'synthesia' | 'workspace'\n});\n```\n\n#### Get Template\n\n```typescript\nconst result = await synthesia.templates.getTemplate(\"template-id\");\n```\n\n### Webhooks API\n\n#### Create Webhook\n\n```typescript\nconst result = await synthesia.webhooks.createWebhook({\n  url: \"https://your-app.com/webhook\",\n  events: [\"video.completed\", \"video.failed\"],\n  secret: \"your-webhook-secret\", // Optional but recommended\n});\n```\n\n#### List Webhooks\n\n```typescript\nconst result = await synthesia.webhooks.listWebhooks();\n```\n\n#### Get Webhook\n\n```typescript\nconst result = await synthesia.webhooks.getWebhook(\"webhook-id\");\n```\n\n#### Update Webhook\n\n```typescript\n// Note: Update webhook is not available in the API\n// Use delete and create instead\nawait synthesia.webhooks.deleteWebhook(\"webhook-id\");\nconst result = await synthesia.webhooks.createWebhook({\n  url: \"https://your-app.com/webhook\",\n  events: [\"video.completed\"],\n});\n```\n\n#### Delete Webhook\n\n```typescript\nconst result = await synthesia.webhooks.deleteWebhook(\"webhook-id\");\n```\n\n### Uploads API\n\n#### Upload Asset\n\n```typescript\nconst file = Buffer.from(\"image data\");\nconst result = await synthesia.uploads.uploadAsset({\n  file,\n  contentType: \"image/png\",\n});\n```\n\n#### Upload Script Audio\n\n```typescript\nconst audioBuffer = Buffer.from(\"mp3 audio data\");\nconst result = await synthesia.uploads.uploadScriptAudio(audioBuffer);\n```\n\n## Error Handling\n\nThe SDK provides comprehensive error handling with custom error types:\n\n```typescript\nimport {\n  SynthesiaSDKError,\n  ValidationError,\n  AuthenticationError,\n} from \"@androettop/synthesia-sdk\";\n\ntry {\n  const result = await synthesia.videos.createVideo({\n    title: \"Test Video\",\n  });\n\n  if (result.error) {\n    throw SynthesiaSDKError.fromResponse(result.error);\n  }\n} catch (error) {\n  if (error instanceof AuthenticationError) {\n    console.error(\"Authentication failed:\", error.message);\n  } else if (error instanceof ValidationError) {\n    console.error(\"Validation error:\", error.message, error.details);\n  } else if (error instanceof SynthesiaSDKError) {\n    console.error(\"Synthesia API error:\", error.message);\n\n    if (error.isRateLimited()) {\n      console.log(\"Rate limited, retry after:\", error.retryAfter);\n    }\n  }\n}\n```\n\n## Utilities\n\nThe SDK includes utility functions for common tasks:\n\n```typescript\nimport { SynthesiaUtils } from \"@androettop/synthesia-sdk\";\n\n// Validate webhook signatures\nconst isValid = SynthesiaUtils.validateWebhookSignature(\n  payload,\n  signature,\n  secret\n);\n\n// Poll video status until completion\nconst finalStatus = await SynthesiaUtils.pollVideoStatus(\n  (id) => synthesia.videos.getVideo(id),\n  \"video-id\",\n  {\n    maxAttempts: 60,\n    intervalMs: 10000,\n    onStatusUpdate: (status) => console.log(\"Status:\", status),\n  }\n);\n```\n\n## Rate Limiting\n\nTrack rate limit information:\n\n```typescript\nconst result = await synthesia.videos.createVideo(videoData);\nconst rateLimitInfo = synthesia.getRateLimitInfo();\n\nif (rateLimitInfo) {\n  console.log(\"Rate limit:\", rateLimitInfo.limit);\n  console.log(\"Remaining:\", rateLimitInfo.remaining);\n  console.log(\"Reset at:\", rateLimitInfo.resetAt);\n}\n```\n\n## Webhook Handling\n\nExample webhook handler:\n\n```typescript\nimport { SynthesiaUtils } from \"@androettop/synthesia-sdk\";\nimport express from \"express\";\n\nconst app = express();\n\napp.post(\"/webhook\", express.raw({ type: \"application/json\" }), (req, res) => {\n  const payload = req.body.toString();\n  const signature = req.headers[\"x-signature\"] as string;\n  const secret = \"your-webhook-secret\";\n\n  if (!SynthesiaUtils.validateWebhookSignature(payload, signature, secret)) {\n    return res.status(401).send(\"Invalid signature\");\n  }\n\n  const data = JSON.parse(payload);\n\n  switch (data.event) {\n    case \"video.completed\":\n      console.log(\"Video completed:\", data.video.id);\n      // Handle video completion\n      break;\n\n    case \"video.failed\":\n      console.log(\"Video failed:\", data.video.id);\n      // Handle video failure\n      break;\n  }\n\n  res.status(200).send(\"OK\");\n});\n```\n\n## Examples\n\nCheck the `examples/` directory for complete usage examples:\n\n- `basic-usage.ts` - Basic video creation and management\n- `template-usage.ts` - Working with templates\n- `webhook-usage.ts` - Setting up and handling webhooks\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build the project\nnpm run build\n\n# Run linting\nnpm run lint\n```\n\n## API Coverage\n\nThis SDK implements all available Synthesia API endpoints:\n\n### Videos API ✅\n\n- [x] Create Video\n- [x] List Videos\n- [x] Get Video\n- [x] Update Video\n- [x] Delete Video\n- [x] Create Video from Template\n\n### Templates API ✅\n\n- [x] List Templates\n- [x] Get Template\n\n### Webhooks API ✅\n\n- [x] Create Webhook\n- [x] List Webhooks\n- [x] Get Webhook\n- [x] Update Webhook\n- [x] Delete Webhook\n\n### Upload API ✅\n\n- [x] Upload Assets  \n- [x] Upload Script Audio\n- [x] Upload Images (via uploadImage helper)\n- [x] Upload Videos (via uploadVideo helper)\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## Support\n\nFor issues with this SDK, please create an issue on GitHub.\n\nFor Synthesia API questions, consult the [official documentation](https://docs.synthesia.io/).\n","readmeFilename":"README.md"}