{"sections":[{"id":"getting-started","title":"Getting Started","content":"Sign up, verify your domain via DNS TXT, create an API key, sign a JWT, and start generating OG images."},{"id":"authentication","title":"Authentication","content":"Authenticate by sending a signed JWT in the request body as token. The JWT payload must include iss (verified domain) and sub (API key prefix). Domain ownership must be verified."},{"id":"api-reference","title":"API Reference","content":"Complete API endpoint documentation"},{"id":"templates","title":"Templates","content":"Available templates and their parameters"},{"id":"integration-guides","title":"Integration Guides","content":"Platform-specific integration guides"}],"templates":[{"name":"page","description":"Default template for landing pages, homepages, and general content","default":true,"parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Main headline (max 60 chars)"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"description","type":"string","required":false,"description":"Subtitle text (max 100 chars)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"blog_post","description":"Optimized for blog articles with author info and publication date","parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Main headline (max 60 chars)"},{"name":"author_avatar_url","type":"string","required":false,"description":"Author avatar URL"},{"name":"author_name","type":"string","required":false,"description":"Author name"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"publish_date","type":"string","required":false,"description":"Publication date (ISO 8601)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"podcast","description":"Designed for podcast episodes with episode metadata","parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Episode title"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"episode_date","type":"string","required":false,"description":"Episode date (ISO 8601)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"product","description":"E-commerce product pages with USP badges","parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Product name"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"},{"name":"unique_selling_point","type":"string","required":false,"description":"USP badge text"}]},{"name":"event","description":"Event pages with date, location, and ticket info","parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Event name"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"event_date","type":"string","required":false,"description":"Event date or range"},{"name":"event_location","type":"string","required":false,"description":"Event location"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"book","description":"Book and publication pages","parameters":[{"name":"book_author","type":"string","required":true,"description":"Book author"},{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Book title"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"book_description","type":"string","required":false,"description":"Longer description"},{"name":"book_genre","type":"string","required":false,"description":"Book genre"},{"name":"book_series_number","type":"integer","required":false,"description":"Series number"},{"name":"description","type":"string","required":false,"description":"Book description"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"portfolio","description":"Personal portfolio and profile pages","parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Main headline (max 60 chars)"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"description","type":"string","required":false,"description":"Subtitle text (max 100 chars)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"company","description":"Company profile and careers pages with centered branding (use company_logo_url for the centered mark)","parameters":[{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Company name"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"company_logo_url","type":"string","required":false,"description":"Centered company logo URL"},{"name":"description","type":"string","required":false,"description":"Supporting text (e.g., open roles count, metrics, etc.)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]},{"name":"github","description":"GitHub contribution graph (7 rows, 26 columns)","parameters":[{"name":"contributions","type":"array<object>","required":true,"description":"Contribution cells as [{date,count}] (preferred). The last 175 days are shown, with missing dates auto-filled as 0. Single {date,count} objects and date=>count maps are also accepted."},{"name":"description","type":"string","required":true,"description":"Summary line (e.g., '328 code changes in the last 7 days.')"},{"name":"iss","type":"string","required":true,"description":"Verified domain hostname for your account"},{"name":"sub","type":"string","required":true,"description":"API key prefix (first 8 chars of your key)"},{"name":"title","type":"string","required":true,"description":"Header title (organization or repository name)"},{"name":"accent_color","type":"string","required":false,"default":"#e6a91a","description":"Accent color used for contribution intensity levels"},{"name":"bg_color","type":"string","required":false,"default":"#ffffff","description":"Background color (hex)"},{"name":"iat","type":"integer","required":false,"description":"Issued-at timestamp for daily cache busting"},{"name":"image_url","type":"string","required":false,"description":"URL to main/hero image"},{"name":"logo_url","type":"string","required":false,"description":"URL to your brand logo"},{"name":"path","type":"string","required":false,"description":"Request path for per-page analytics (for example: /blog/my-post)"},{"name":"template","type":"string","required":false,"default":"page","description":"Template type"},{"name":"text_color","type":"string","required":false,"default":"#1a1a1a","description":"Text color (hex)"}]}],"examples":{"curl":"curl -X POST \"https://ogpilot.com/api/v1/images\"   -H \"Content-Type: application/json\"   -H \"Accept: application/json\"   -d '{\"token\":\"YOUR_JWT_TOKEN\"}'\n","javascript":"// npm install og-pilot-js@^0.4.2\n\nimport { configure, createImage } from \"og-pilot-js\";\n\nconfigure((config) => {\n  config.apiKey = process.env.OG_PILOT_API_KEY;\n  config.domain = process.env.OG_PILOT_DOMAIN ?? \"yourdomain.com\";\n});\n\nconst imageUrl = await createImage(\n  {\n    template: \"blog_post\",\n    title: \"How to Build Amazing OG Images\",\n    description: \"A complete guide to social media previews\",\n    author_name: \"Jane Smith\",\n    publish_date: \"2024-01-15\",\n    path: \"/blog/how-to-build-amazing-og-images\"\n  },\n  {iat: Date.now()} // optional: refresh cache daily\n);\n\nconsole.log(\"OG Image URL:\", imageUrl);\n","python":"# pip install og-pilot==0.4.1\n\nimport os\nimport time\nimport og_pilot\n\nog_pilot.configure(\n    api_key=os.environ[\"OG_PILOT_API_KEY\"],\n    domain=os.environ.get(\"OG_PILOT_DOMAIN\", \"yourdomain.com\"),\n)\n\nog_image = og_pilot.create_image(\n    template=\"blog_post\",\n    title=\"How to Build Amazing OG Images\",\n    description=\"A complete guide to social media previews\",\n    author_name=\"Jane Smith\",\n    publish_date=\"2024-01-15\",\n    path=\"/blog/how-to-build-amazing-og-images\",\n    iat=int(time.time()),\n)\n\nprint(f\"OG Image URL: {og_image}\")\n","ruby":"# Gemfile\ngem \"og_pilot_ruby\", \"~> 0.4.1\"\n\n# Install and generate the initializer\n# bundle install\n# bin/rails g og_pilot_ruby:install\n\n# The generator creates config/initializers/og_pilot_ruby.rb.\n# Set OG_PILOT_API_KEY and OG_PILOT_DOMAIN in your environment.\n\nclass PostsController < ApplicationController\n  def show\n    @post = Post.find(params[:id])\n\n    @og_image = OgPilotRuby.create_blog_post_image(\n      title: @post.title,\n      description: @post.excerpt,\n      author_name: @post.author.name,\n      publish_date: @post.published_at.to_date.iso8601,\n      image_url: @post.featured_image_url,\n      path: request.fullpath,\n      iat: Time.current.to_i\n    )\n  end\nend\n\n# In your layout/view (direct gem usage, no wrapper service needed):\n# <meta property=\"og:image\" content=\"<%= @og_image %>\" />\n# <meta name=\"twitter:image\" content=\"<%= @og_image %>\" />\n","php":"<?php\n// composer require sunergos/og-pilot-php\nuse Sunergos\\OgPilot\\Facades\\OgPilot;\n\n$imageUrl = OgPilot::createImage(\n    [\n        'template' => 'blog_post',\n        'title' => 'How to Build Amazing OG Images',\n        'description' => 'A complete guide to social media previews',\n        'author_name' => 'Jane Smith',\n        'publish_date' => '2024-01-15',\n        'path' => '/blog/how-to-build-amazing-og-images',\n    ],\n    [\n        'iat' => time(), // optional: refresh cache daily\n    ]\n);\n\necho \"OG Image URL: \" . $imageUrl;\n"},"openapi":{"openapi":"3.0.3","info":{"title":"OG Pilot API","version":"1.0.0","description":"Generate dynamic Open Graph images"},"servers":[{"url":"https://ogpilot.com/api/v1"}],"tags":[{"name":"Images","description":"Generate Open Graph images from signed JWT payloads."}],"paths":{"/images":{"post":{"tags":["Images"],"summary":"Generate OG image","description":"POST endpoint that accepts a signed JWT in the request body (`token`). Returns redirect to CDN URL by default, or JSON metadata if Accept: application/json header is present. If the image is still processing, returns 202.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"},"examples":{"basic":{"value":{"token":"YOUR_JWT_TOKEN"}}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"302":{"description":"Redirect to CDN URL (default HTML/PNG behavior)","headers":{"Location":{"schema":{"type":"string","format":"uri"},"description":"CDN URL of generated image"},"X-OG-Pilot-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]},"description":"Cache status"}}},"200":{"description":"Image metadata (JSON response when Accept: application/json header is present)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"},"examples":{"completed":{"value":{"id":"s_abc123","status":"completed","url":"https://cdn.ogpilot.com/images/s_abc123.jpg","width":1200,"height":630,"created_at":"2026-02-06T12:00:00Z","cached":true,"stale":false}}}}}},"202":{"description":"Image is processing; JSON includes metadata and optional placeholder_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"},"examples":{"processing":{"value":{"id":"s_abc123","status":"processing","url":"https://ogpilot.com/status/processing.jpg","width":1200,"height":630,"created_at":"2026-02-06T12:00:00Z","cached":false,"stale":false,"placeholder_url":"https://ogpilot.com/status/processing.jpg"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"TokenRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Signed JWT token generated in your application."}}},"ImageResponse":{"type":"object","required":["id","status","url","width","height","created_at","cached","stale"],"properties":{"id":{"type":"string","example":"s_abc123"},"status":{"type":"string","enum":["processing","completed","failed"],"example":"completed"},"url":{"type":"string","format":"uri","example":"https://cdn.ogpilot.com/images/s_abc123.jpg"},"width":{"type":"integer","example":1200},"height":{"type":"integer","example":630},"created_at":{"type":"string","format":"date-time","example":"2026-02-06T12:00:00Z"},"cached":{"type":"boolean","example":true},"stale":{"type":"boolean","example":false},"placeholder_url":{"type":"string","format":"uri","nullable":true},"error":{"type":"string","nullable":true}}},"ErrorResponse":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","example":"Invalid or expired JWT token"},"code":{"type":"string","example":"unauthorized"},"details":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object"}],"nullable":true}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad request","code":"bad_request"}}}},"Unauthorized":{"description":"Missing/invalid token or invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid or expired JWT token","code":"unauthorized"}}}},"Forbidden":{"description":"Domain not verified or subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Domain not verified for this account","code":"forbidden"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Not found","code":"not_found"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Validation failed","code":"validation_error","details":["Title can't be blank"]}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Rate limit exceeded","code":"rate_limited"}}}}}}}}