Create prompts with nested schemas

Build the segment-level schema first

Start with the evidence-level fields you need per segment.

For schema-aware video metadata extraction, treat the schema as the public contract that operators, search filters, exports, and downstream applications will reuse. Stable nested field names make JSON schema media extraction easier to query after prompt runs complete.

{
  "type": "object",
  "properties": {
    "headline": { "type": "string" },
    "scene": {
      "type": "object",
      "properties": {
        "location": { "type": "string" },
        "people": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "emotion": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

Create the prompt

from videovector import VideoVector

schema = {
    "type": "object",
    "properties": {
        "headline": {"type": "string"},
        "scene": {
            "type": "object",
            "properties": {
                "location": {"type": "string"},
                "people": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {"type": "string"},
                            "emotion": {"type": "string"},
                        },
                    },
                },
            },
        },
    },
}

with VideoVector(api_key="sk_live_...") as client:
    prompt = client.prompts.create(
        name="Segment scene extractor",
        description="Extract scene-level review metadata.",
        prompt_text="Extract the requested fields from this media segment.",
        json_schema=schema,
        semantic_indexing={
            "disabled_segment_fields": [],
            "disabled_video_level_fields": [],
        },
    )

Validate the schema against sample data

Use the public schema test surface before you save or publish a contract that downstream systems rely on.

curl -X POST https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2/prompts/test-schema \
  -H "Authorization: Bearer <token-or-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "json_schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" }
      }
    },
    "sample_data": {
      "headline": "Crowd gathers near station entrance"
    }
  }'

Keep the schema query-friendly

• Use stable field names.
• Avoid ., [ and ] in field names.
• Treat repeated object fields as future filter paths such as scene.people[].emotion.
• Disable semantic indexing only when a field should stay in structured output but not in embeddings.

When to add video-level synthesis

If the workflow also needs one result per media item, add video_level after the segment-level schema is stable. That keeps evidence extraction and media-wide synthesis as separate contracts.