API Documentation

https://altframe.app

x-api-key: af_live_your_api_key

# or

Authorization: Bearer af_live_your_api_key

{
  "id": "job_abc123",
  "status": "completed",
  "results": {
    "alt_text": "Hands planting organic tomato seeds in rich dark soil in a raised garden bed",
    "title": "Planting Organic Tomato Seeds in Garden",
    "caption": "A gardener carefully plants organic tomato seeds into nutrient-rich soil in a raised bed.",
    "og_description": "Learn sustainable gardening with organic tomato seed planting techniques."
  },
  "meta": {
    "language": "en",
    "model": "gpt-4.1-nano",
    "tokens": { "input": 1180, "output": 142 },
    "processing_ms": 820,
    "credits_used": 1,
    "credits_remaining": 999
  }
}

{
  "id": "job_abc123",
  "status": "completed",
  "results": {
    "alt_text": "Hands planting organic tomato seeds in rich dark soil in a raised garden bed",
    "title": "Planting Organic Tomato Seeds in Garden",
    "caption": "A gardener carefully plants organic tomato seeds into nutrient-rich soil in a raised bed.",
    "og_description": "Learn sustainable gardening with organic tomato seed planting techniques."
  },
  "meta": {
    "language": "en",
    "model": "gpt-4.1-nano",
    "tokens": { "input": 1180, "output": 142 },
    "processing_ms": 820,
    "credits_used": 1,
    "credits_remaining": 999
  }
}

{
  "batch_id": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
  "total_images": 3,
  "credits_reserved": 3,
  "estimated_seconds": 6,
  "status_url": "/api/v1/batches/b47ac10b-58cc-4372-a567-0e02b2c3d479"
}

{
  "batch_id": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "total": 3,
  "completed": 3,
  "failed": 0,
  "results": [
    {
      "id": "job_def456",
      "image_url": "https://example.com/product-1.jpg",
      "results": {
        "alt_text": "Packet of organic heirloom tomato seeds with planting instructions",
        "title": "Organic Heirloom Tomato Seeds"
      },
      "meta": {
        "model": "gpt-4.1-nano",
        "tokens": { "input": 1024, "output": 96 },
        "processing_ms": 740
      }
    },
    {
      "id": "job_ghi789",
      "image_url": "https://example.com/product-2.jpg",
      "results": {
        "alt_text": "Three-piece stainless steel garden trowel set with ergonomic handles",
        "title": "3-Piece Garden Trowel Set"
      },
      "meta": {
        "model": "gpt-4.1-nano",
        "tokens": { "input": 980, "output": 88 },
        "processing_ms": 690
      }
    },
    {
      "id": "job_jkl012",
      "image_url": "https://example.com/product-3.jpg",
      "results": {
        "alt_text": "Wooden raised garden bed kit with soil and seedlings",
        "title": "Raised Garden Bed Starter Kit"
      },
      "meta": {
        "model": "gpt-4.1-nano",
        "tokens": { "input": 1100, "output": 102 },
        "processing_ms": 810
      }
    }
  ],
  "errors": []
}

{
  "jobs": [
    {
      "id": "job_abc123",
      "status": "completed",
      "image_url": "https://example.com/photo.jpg",
      "results": {
        "alt_text": "Hands planting organic tomato seeds in rich dark soil",
        "title": "Planting Organic Tomato Seeds",
        "caption": "A gardener plants tomato seeds into nutrient-rich soil.",
        "og_description": "Sustainable organic tomato seed planting techniques."
      },
      "mode": "standard",
      "language": "en",
      "meta": {
        "model": "gpt-4.1-nano",
        "tokens": { "input": 1180, "output": 142 },
        "processing_ms": 820,
        "cost_usd": 0.0004
      },
      "source": "api",
      "batch_id": null,
      "error": null,
      "created_at": "2025-07-15T10:30:00.000Z",
      "completed_at": "2025-07-15T10:30:00.820Z"
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

{
  "plan": "pro",
  "credits": {
    "monthly_allocation": 5000,
    "remaining": 4832,
    "rollover": 0,
    "used_this_period": 168,
    "period_resets_at": "2025-08-01T00:00:00.000Z"
  },
  "overage": {
    "enabled": true,
    "rate": 0.03
  }
}

// Your server receives a POST request when a batch completes:

POST https://yourapp.com/webhooks/altframe
Content-Type: application/json

{
  "event": "batch.completed",
  "batch_id": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "total": 3,
  "completed": 3,
  "failed": 0,
  "results": [
    {
      "id": "job_def456",
      "image_url": "https://example.com/product-1.jpg",
      "results": {
        "alt_text": "Packet of organic heirloom tomato seeds",
        "title": "Organic Heirloom Tomato Seeds"
      }
    }
  ],
  "errors": []
}

// Express.js webhook handler example

app.post("/webhooks/altframe", (req, res) => {
  const { event, batch_id, status, results, errors } = req.body;

  if (event === "batch.completed") {
    console.log(`Batch ${batch_id} finished: ${status}`);

    // Update your database with the generated alt text
    for (const item of results) {
      db.images.update({
        where: { url: item.image_url },
        data: {
          alt_text: item.results.alt_text,
          title: item.results.title,
        },
      });
    }

    // Handle any failures
    for (const err of errors) {
      console.error(`Failed: ${err.image_url} - ${err.error}`);
    }
  }

  res.status(200).json({ received: true });
});

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1700000060