Skip to main content
POST /v1/app-ad-creatives/generate
GET  /v1/app-ad-creatives/jobs/:jobId
Create a finished mobile app ad from a real store listing. Appeeky analyzes the app’s title, description, icon, screenshots, audience, and positioning, then returns:
  • confirmed product key points
  • paste-ready Meta primary text, headline, description, and call to action
  • a square 1024x1024 PNG creative generated from the app’s real icon and screenshots
  • the final prompt used to generate the creative
The work runs asynchronously on Trigger.dev. POST /v1/app-ad-creatives/generate returns a jobId immediately with HTTP 202; poll GET /v1/app-ad-creatives/jobs/:jobId until the job is completed or failed.
Generated creatives use real listing assets as references. When screenshots are available, Appeeky composites the actual app UI into the creative instead of inventing unrelated product screens.

​
Create a creative job

POST /v1/app-ad-creatives/generate

​
Request body

FieldTypeRequiredDefaultDescription
appUrlstringConditional—App Store or Google Play listing URL. Required unless platform + appId are provided.
platformstringConditional—apple or google. Required when using appId instead of appUrl.
appIdstringConditional—Apple numeric app ID or Google Play package name. Required when using platform.
countrystringNousStorefront country, ISO 3166-1 alpha-2.
langstringNoenGoogle Play language code.
modestringNogenerateanalyze, generate, or edit.
stylestringNougcCreative direction. Built-ins: ugc, professional, problem_solution, before_after, lifestyle. Custom strings are also accepted.
anglestringNoinferredOptional ad angle, e.g. problem-solution for busy founders.
audiencestringNoinferredOptional target audience override.
keyPointsobjectNoinferredUser-confirmed product facts to steer the ad.
extraScreenshotUrlsstring[]No[]Additional public screenshots to use as visual references.
generateImagebooleanNotrueSet false to only analyze the listing and generate copy.
qualitystringNomediumImage quality: low, medium, or high.
editInstructionstringRequired for edit—Natural-language edit instruction, e.g. Make the headline bigger and use a navy background.
previousAdobjectNo—Previous ad object when using mode: "edit".

​
Credits

ModeCreditsNotes
analyze1Listing analysis + key points + copy, no image.
generate10New square ad image + copy.
edit3Modify an existing ad with a sentence.
generateImage: false1Copy-only run, regardless of mode.
You can pass X-OpenAI-Key to use your own OpenAI key. In that case Appeeky does not use the platform OpenAI key for generation. The key is not stored in the job record.

​
Code examples

curl -X POST "https://api.appeeky.com/v1/app-ad-creatives/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appUrl": "https://apps.apple.com/us/app/forest-focus-for-productivity/id866450515",
    "country": "us",
    "mode": "generate",
    "style": "ugc",
    "angle": "problem-solution for people distracted by their phones",
    "audience": "students and knowledge workers"
  }'

​
Response (202 Accepted)

{
  "data": {
    "jobId": "4b8419b6-0d3a-4ab7-a8e8-6d1f4b53d414",
    "triggerRunId": "run_abc123",
    "status": "queued",
    "mode": "generate"
  }
}

​
Poll job status

GET /v1/app-ad-creatives/jobs/:jobId

​
Response while running

{
  "data": {
    "jobId": "4b8419b6-0d3a-4ab7-a8e8-6d1f4b53d414",
    "status": "processing",
    "mode": "generate",
    "input": {
      "appUrl": "https://apps.apple.com/us/app/forest-focus-for-productivity/id866450515",
      "country": "us",
      "mode": "generate",
      "style": "ugc"
    },
    "result": null,
    "error": null,
    "triggerRunId": "run_abc123",
    "createdAt": "2026-06-25T08:42:11.000Z",
    "updatedAt": "2026-06-25T08:42:16.000Z"
  }
}

​
Response when completed

{
  "data": {
    "jobId": "4b8419b6-0d3a-4ab7-a8e8-6d1f4b53d414",
    "status": "completed",
    "mode": "generate",
    "result": {
      "listing": {
        "platform": "apple",
        "appId": "866450515",
        "country": "us",
        "lang": null,
        "title": "Forest: Focus for Productivity",
        "developer": "SEEKRTECH CO., LTD.",
        "url": "https://apps.apple.com/us/app/id866450515",
        "iconUrl": "https://...",
        "description": "Stay focused, be present...",
        "category": "Productivity",
        "rating": 4.8,
        "reviewsCount": 424000,
        "isFree": false,
        "screenshots": ["https://...", "https://..."]
      },
      "keyPoints": {
        "whatItDoes": "Helps users stay off their phone and focus by growing virtual trees.",
        "targetAudience": "Students and knowledge workers who get distracted by their phones.",
        "painPoint": "They keep losing focus to quick phone checks.",
        "promise": "Turn focused time into a simple visual reward.",
        "brandTone": "Calm, motivating, nature-inspired.",
        "visualDirection": "Show real app screens inside a clean phone mockup with a focus-progress hook.",
        "adAngle": "Problem-solution"
      },
      "assets": {
        "iconUrl": "https://...",
        "screenshotUrls": ["https://...", "https://..."],
        "referenceImageCount": 4
      },
      "ad": {
        "id": "cb02a6a2-b01f-43b3-a02f-58b4863d9f8e",
        "style": "ugc",
        "angle": "Problem-solution",
        "imageUrl": "https://assets.appeeky.com/app-ad-creatives/cb02.../square.png",
        "width": 1024,
        "height": 1024,
        "format": "png",
        "copy": {
          "primaryText": "Your phone keeps pulling you away from deep work. Forest turns focus into a tiny reward: plant a tree, stay present, and watch your progress grow.",
          "headline": "Grow your focus",
          "description": "Stay off your phone and get more done.",
          "callToAction": "DOWNLOAD"
        },
        "creativeHeadline": "Stop checking your phone",
        "creativeSubhead": "Grow a tree every time you stay focused.",
        "prompt": "Create a square 1024x1024 Meta/Instagram ad creative...",
        "generatedAt": "2026-06-25T08:43:04.000Z"
      }
    },
    "error": null,
    "triggerRunId": "run_abc123",
    "createdAt": "2026-06-25T08:42:11.000Z",
    "updatedAt": "2026-06-25T08:43:04.000Z"
  }
}

​
Job fields

FieldTypeDescription
statusstringqueued, processing, completed, or failed.
modestringThe requested mode: analyze, generate, or edit.
inputobjectThe safe job input. Sensitive BYOK values are not stored here.
resultobjectThe completed creative payload. null until the job completes.
errorstringFailure message when status is failed; otherwise null.
triggerRunIdstringTrigger.dev run identifier for support/debugging.

​
Edit an existing ad

Use mode: "edit" with a previous ad object and a natural-language instruction.
cURL
curl -X POST "https://api.appeeky.com/v1/app-ad-creatives/generate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appUrl": "https://apps.apple.com/us/app/forest-focus-for-productivity/id866450515",
    "mode": "edit",
    "editInstruction": "Make the headline bigger and change the background to navy.",
    "previousAd": {
      "style": "ugc",
      "creativeHeadline": "Stop checking your phone",
      "creativeSubhead": "Grow a tree every time you stay focused."
    }
  }'

​
Errors

StatusCodeWhen
400INVALID_REQUESTMissing or invalid app URL, app ID, platform, or edit instruction.
401MISSING_AUTHNo Authorization: Bearer <token> or X-API-Key header.
401INVALID_API_KEYInvalid or inactive API key.
403PRO_FEATUREThe API key owner is not on a Pro plan.
404APP_NOT_FOUNDThe app listing could not be found in the requested storefront.
404JOB_NOT_FOUNDThe requested job ID does not exist.
503OPENAI_NOT_CONFIGUREDServer-side OpenAI credentials are not configured and no X-OpenAI-Key was provided.